summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source')
-rw-r--r--docs/source/commandline/commandline-all.rst40
-rw-r--r--docs/source/commandline/commandline-index.rst5
-rw-r--r--docs/source/techspecs/layout_files.rst231
3 files changed, 86 insertions, 190 deletions
diff --git a/docs/source/commandline/commandline-all.rst b/docs/source/commandline/commandline-all.rst
index acbd9b50099..c5bced793c5 100644
--- a/docs/source/commandline/commandline-all.rst
+++ b/docs/source/commandline/commandline-all.rst
@@ -1504,46 +1504,6 @@ Core Artwork Options
The default is OFF **-noartwork_crop**.
-.. _mame-commandline-nousebackdrops:
-
-**-[no]use_backdrops** / **-[no]backdrop**
-
- Enables/disables the display of backdrops.
-
- The default is ON (**-use_backdrops**).
-
-.. _mame-commandline-nouseoverlays:
-
-**-[no]use_overlays** / **-[no]overlay**
-
- Enables/disables the display of overlays.
-
- The default is ON (**-use_overlays**).
-
-.. _mame-commandline-nousebezels:
-
-**-[no]use_bezels** / **-[no]bezels**
-
- Enables/disables the display of bezels.
-
- The default is ON (**-use_bezels**).
-
-.. _mame-commandline-nousecpanels:
-
-**-[no]use_cpanels** / **-[no]cpanels**
-
- Enables/disables the display of control panels.
-
- The default is ON (**-use_cpanels**).
-
-.. _mame-commandline-nousemarquees:
-
-**-[no]use_marquees** / **-[no]marquees**
-
- Enables/disables the display of marquees.
-
- The default is ON (**-use_marquees**).
-
.. _mame-commandline-fallbackartwork:
**-fallback_artwork**
diff --git a/docs/source/commandline/commandline-index.rst b/docs/source/commandline/commandline-index.rst
index a81c85ef4cc..b2caa063d14 100644
--- a/docs/source/commandline/commandline-index.rst
+++ b/docs/source/commandline/commandline-index.rst
@@ -191,11 +191,6 @@ Core Artwork Options
~~~~~~~~~~~~~~~~~~~~
| :ref:`[no]artwork_crop <mame-commandline-noartworkcrop>`
-| :ref:`[no]use_backdrops <mame-commandline-nousebackdrops>`
-| :ref:`[no]use_overlays <mame-commandline-nouseoverlays>`
-| :ref:`[no]use_bezels <mame-commandline-nousebezels>`
-| :ref:`[no]use_cpanels <mame-commandline-nousecpanels>`
-| :ref:`[no]use_marquees <mame-commandline-nousemarquees>`
| :ref:`fallback_artwork <mame-commandline-fallbackartwork>`
| :ref:`override_artwork <mame-commandline-overrideartwork>`
diff --git a/docs/source/techspecs/layout_files.rst b/docs/source/techspecs/layout_files.rst
index 10467a8d0e9..bc05720a692 100644
--- a/docs/source/techspecs/layout_files.rst
+++ b/docs/source/techspecs/layout_files.rst
@@ -99,7 +99,7 @@ gamuts, so colours will typically be interpreted as sRGB with your system's
target gamma (usually 2.2). Channel values are specified as floating-point
numbers. Red, green and blue channel values range from 0.0 (off) to 1.0 (full
intensity). Alpha ranges from 0.0 (fully transparent) to 1.0 (opaque). Colour
-channels values are not pre-multiplied by the alpha value.
+channel values are not pre-multiplied by the alpha value.
Component and view item colour is specified using ``color`` elements.
Meaningful attributes are ``red``, ``green``, ``blue`` and ``alpha``. This
@@ -123,9 +123,9 @@ parameter is not defined, no substitution occurs. Here is an examples showing
two instances of parameter use -- the values of the ``digitno`` and ``x``
parameters will be substituted for ``~digitno~`` and ``~x~``::
- <bezel name="digit~digitno~" element="digit">
+ <element name="digit~digitno~" ref="digit">
<bounds x="~x~" y="80" width="25" height="40" />
- </bezel>
+ </element>
A parameter name is a sequence of uppercase English letters A-Z, lowercase
English letters a-z, decimal digits 0-9, and/or underscore (_) characters.
@@ -319,64 +319,6 @@ end of configuration. Values are not updated and layouts are not recomputed if
the system reconfigures the screen while running.
-.. _layout-concepts-layers:
-
-Layers
-~~~~~~
-
-Views are rendered as a stack of layers, named after parts of an arcade cabinet.
-The layout supplies elements to be drawn in all layers besides the screen layer,
-which is reserved for emulated screens. With the exception of the screen layer,
-users can enable or disable layers using the in-emulation menu or command-line
-options.
-
-The following layers are available:
-
-backdrop
- Intended for use in situations were the screen image is projected over a
- backdrop using a semi-reflective mirror (Pepper's ghost). This arrangement
- is famously used in the Space Invaders deluxe cabinet.
-screen
- This layer is reserved for emulated screen images, and cannot be disabled by
- the user. It is drawn using additive blending.
-overlay
- This layer is intended for use translucent overlays used to add colour to
- games using monochrome monitors like Circus, Gee Bee, and of course Space
- Invaders. It is drawn using RGB multiplication.
-bezel
- This layer is for elements that surround and potentially obscure the screen
- image. It is drawn with standard alpha blending.
-cpanel
- This layer is intended for displaying controls/input devices (control
- panels). It is drawn using standard alpha blending.
-marquee
- This layer is intended for displaying arcade cabinet marquee images. It is
- drawn using standard alpha blending.
-
-By default, layers are drawn in this order (from back to front):
-
-* screen (add)
-* overlay (multiply)
-* backdrop (add)
-* bezel (alpha)
-* cpanel (alpha)
-* marquee (alpha)
-
-If a view has multiple backdrop elements and no overlay elements, a different
-order is used (from back to front):
-
-* backdrop (alpha)
-* screen (add)
-* bezel (alpha)
-* cpanel (alpha)
-* marquee (alpha)
-
-The alternate drawing order makes it simpler to build a backdrop from multiple
-scanned/traced pieces of art, as they can have opaque parts. It can't be used
-with overlay elements because colour overlays are conventionally placed between
-the screen and mirror, and as such do not affect the backdrop.
-
-
.. _layout-parts:
Parts of a layout
@@ -651,15 +593,14 @@ bounds
param
Defines or reassigns a value parameter in the view's scope. See
:ref:`layout-concepts-params` for details.
-backdrop overlay bezel cpanel marquee
- Adds an element to the relevant layer (see :ref:`layout-parts-elements` and
- :ref:`layout-concepts-layers`). The name of the element to add is specified
- using the required ``element`` attribute. It is an error if no element with
- this name is defined in the layout file. May optionally be connected to an
- emulated I/O port using ``inputtag`` and ``inputmask`` attributes, and/or an
- emulated output using a ``name`` attribute. Within a layer, elements are
- drawn in the order they appear in the layout file, from front to back. See
- below for more details.
+element
+ Adds an element to the view (see :ref:`layout-parts-elements`). The name of
+ the element to add is specified using the required ``ref`` attribute. It is
+ an error if no element with this name is defined in the layout file. May
+ optionally be connected to an emulated I/O port using ``inputtag`` and
+ ``inputmask`` attributes, and/or an emulated output using a ``name``
+ attribute. Within a layer, elements are drawn in the order they appear in
+ the layout file, from front to back. See below for more details.
screen
Adds an emulated screen image to the view. The screen must be identified
using either an ``index`` attribute or a ``tag`` attribute (it is an error
@@ -677,18 +618,16 @@ group
repeat
Repeats its contents the number of times specified by the required ``count``
attribute. The ``count`` attribute must be a positive integer. A
- ``repeat`` element in a view may contain ``backdrop``, ``screen``,
- ``overlay``, ``bezel``, ``cpanel``, ``marquee``, ``group``, and further
- ``repeat`` elements, which function the same way they do when placed in a
- view directly. See :ref:`layout-parts-repeats` for discussion on using
- ``repeat`` elements.
-
-Screens (``screen`` elements), layout elements (``backdrop``, ``overlay``,
-``bezel``, ``cpanel`` or ``marquee`` elements) and groups (``group`` elements)
-may be have their orientation altered using an ``orientation`` child element.
-For screens, the orientation modifiers are applied in addition to the
-orientation modifiers specified on the screen device and on the machine. The
-``orientation`` element supports the following attributes, all of which are
+ ``repeat`` element in a view may contain ``element``, ``screen``, ``group``,
+ and further ``repeat`` elements, which function the same way they do when
+ placed in a view directly. See :ref:`layout-parts-repeats` for discussion
+ on using ``repeat`` elements.
+
+Screens (``screen`` elements), layout elements (``element`` elements) and groups
+(``group`` elements) may have their orientation altered using an ``orientation``
+child element. For screens, the orientation modifiers are applied in addition
+to the orientation modifiers specified on the screen device and on the machine.
+The ``orientation`` element supports the following attributes, all of which are
optional:
rotate
@@ -708,63 +647,65 @@ flipy
axis, from top to bottom. Must be either ``yes`` or ``no`` if present.
Mirroring applies logically after rotation.
-Screens (``screen`` elements), layout elements (``backdrop``, ``overlay``,
-``bezel``, ``cpanel`` or ``marquee`` elements) and groups (``group`` elements)
-may be positioned and sized using a ``bounds`` child element (see
-:ref:`layout-concepts-coordinates` for details). In the absence of a ``bounds``
-child element, screens' and layout elements' bounds default to a unit square
-(origin at 0,0 and height and width both equal to 1). In the absence of a
-``bounds`` child element, groups are expanded with no translation/scaling (note
-that groups may position screens/elements outside their bounds). This example
-shows a view instantiating and positioning a screen, an individual layout
-element, and two element groups::
+Screens (``screen`` elements) and layout elements (``element`` elements) may
+have a ``blend`` attribute to set the blending mode. Supported values are
+``none`` (no blending), ``alpha`` (alpha blending), ``multiply`` (RGB
+multiplication), and ``add`` (additive blending). The default blending mode for
+screens is additive blending, and the default blending mode for layout elements
+is alpha blending.
+
+Screens (``screen`` elements), layout elements (``element`` elements) and groups
+(``group`` elements) may be positioned and sized using a ``bounds`` child
+element (see :ref:`layout-concepts-coordinates` for details). In the absence of
+a ``bounds`` child element, screens' and layout elements' bounds default to a
+unit square (origin at 0,0 and height and width both equal to 1). In the
+absence of a ``bounds`` child element, groups are expanded with no
+translation/scaling (note that groups may position screens/elements outside
+their bounds). This example shows a view instantiating and positioning a
+screen, an individual layout element, and two element groups::
<view name="LED Displays, Terminal and Keypad">
- <cpanel element="beige"><bounds x="320" y="0" width="172" height="372" /></cpanel>
+ <screen index="0"><bounds x="0" y="132" width="320" height="240" /></screen>
+ <element ref="beige"><bounds x="320" y="0" width="172" height="372" /></element>
<group ref="displays"><bounds x="0" y="0" width="320" height="132" /></group>
<group ref="keypad"><bounds x="336" y="16" width="140" height="260" /></group>
- <screen index="0"><bounds x="0" y="132" width="320" height="240" /></screen>
</view>
-Screens (``screen`` elements), layout elements (``backdrop``, ``overlay``,
-``bezel``, ``cpanel`` or ``marquee`` elements) and groups (``group`` elements)
-may have a ``color`` child element (see :ref:`layout-concepts-colours`)
-specifying a modifier colour. The components colours of the screen or layout
-element(s) are multiplied by this colour.
-
-If an element instantiating a layout element (``backdrop``, ``overlay``,
-``bezel``, ``cpanel`` or ``marquee``) has ``inputtag`` and ``inputmask``
-attributes, clicking it is equivalent to pressing a key/button mapped to the
-corresponding input(s). The ``inputtag`` specifies the tag path of an I/O port
-relative to the device that caused the layout file to be loaded. The
-``inputmask`` attribute must be an integer specifying the bits of the I/O port
-that the element should activate. This sample is shows instantiation of
-clickable buttons::
-
- <cpanel element="btn_3" inputtag="X2" inputmask="0x10">
+Screens (``screen`` elements), layout elements (``element`` elements) and groups
+(``group`` elements) may have a ``color`` child element (see
+:ref:`layout-concepts-colours`) specifying a modifier colour. The component
+colours of the screen or layout element(s) are multiplied by this colour.
+
+If an ``element`` element has ``inputtag`` and ``inputmask`` attributes,
+clicking it is equivalent to pressing a key/button mapped to the corresponding
+input(s). The ``inputtag`` specifies the tag path of an I/O port relative to
+the device that caused the layout file to be loaded. The ``inputmask``
+attribute must be an integer specifying the bits of the I/O port that the
+element should activate. This sample shows instantiation of clickable buttons::
+
+ <element ref="btn_3" inputtag="X2" inputmask="0x10">
<bounds x="2.30" y="4.325" width="1.0" height="1.0" />
- </cpanel>
- <cpanel element="btn_0" inputtag="X0" inputmask="0x20">
- <bounds x="0.725" y="5.375" width="1.0" height="1.0" /></cpanel>
- <cpanel element="btn_rst" inputtag="RESET" inputmask="0x01">
+ </element>
+ <element ref="btn_0" inputtag="X0" inputmask="0x20">
+ <bounds x="0.725" y="5.375" width="1.0" height="1.0" />
+ </element>
+ <element ref="btn_rst" inputtag="RESET" inputmask="0x01">
<bounds x="1.775" y="5.375" width="1.0" height="1.0" />
- </cpanel>
-
+ </element>
-If an element instantiating a layout element (``backdrop``, ``overlay``,
-``bezel``, ``cpanel`` or ``marquee``) has a ``name`` attribute, it will take its
-state from the value of the correspondingly named emulated output. Note that
-output names are global, which can become an issue when a machine uses multiple
-instances of the same type of device. See :ref:`layout-parts-elements` for
-details on how an element's state affects its appearance. This example shows
-how digital displays may be connected to emulated outputs::
+If an ``element`` element has a ``name`` attribute, it will take its state from
+the value of the correspondingly named emulated output. Note that output names
+are global, which can become an issue when a machine uses multiple instances of
+the same type of device. See :ref:`layout-parts-elements` for details on how an
+element's state affects its appearance. This example shows how digital displays
+may be connected to emulated outputs::
- <cpanel name="digit6" element="digit"><bounds x="16" y="16" width="48" height="80" /></cpanel>
- <cpanel name="digit5" element="digit"><bounds x="64" y="16" width="48" height="80" /></cpanel>
- <cpanel name="digit4" element="digit"><bounds x="112" y="16" width="48" height="80" /></cpanel>
- <cpanel name="digit3" element="digit"><bounds x="160" y="16" width="48" height="80" /></cpanel>
- <cpanel name="digit2" element="digit"><bounds x="208" y="16" width="48" height="80" /></cpanel>
- <cpanel name="digit1" element="digit"><bounds x="256" y="16" width="48" height="80" /></cpanel>
+ <element name="digit6" ref="digit"><bounds x="16" y="16" width="48" height="80" /></element>
+ <element name="digit5" ref="digit"><bounds x="64" y="16" width="48" height="80" /></element>
+ <element name="digit4" ref="digit"><bounds x="112" y="16" width="48" height="80" /></element>
+ <element name="digit3" ref="digit"><bounds x="160" y="16" width="48" height="80" /></element>
+ <element name="digit2" ref="digit"><bounds x="208" y="16" width="48" height="80" /></element>
+ <element name="digit1" ref="digit"><bounds x="256" y="16" width="48" height="80" /></element>
If an element instantiating a layout element has ``inputtag`` and ``inputmask``
attributes but lacks a ``name`` attribute, it will take its state from the value
@@ -829,8 +770,8 @@ To demonstrate how bounds calculation works, consider this example::
<group name="autobounds">
<!-- bounds automatically calculated with origin at (5,10), width 30, and height 15 -->
- <cpanel element="topleft"><bounds x="5" y="10" width="10" height="10" /></cpanel>
- <cpanel element="bottomright"><bounds x="25" y="15" width="10" height="10" /></cpanel>
+ <element ref="topleft"><bounds x="5" y="10" width="10" height="10" /></element>
+ <element ref="bottomright"><bounds x="25" y="15" width="10" height="10" /></element>
</group>
<view name="Test">
@@ -850,8 +791,8 @@ positions elements outside its explicit bounds::
<group name="periphery">
<!-- elements are above the top edge and to the right of the right edge of the bounds -->
<bounds x="10" y="10" width="20" height="25" />
- <cpanel element="topleft"><bounds x="10" y="0" width="10" height="10" /></cpanel>
- <cpanel element="bottomright"><bounds x="30" y="20" width="10" height="10" /></cpanel>
+ <element ref="topleft"><bounds x="10" y="0" width="10" height="10" /></element>
+ <element ref="bottomright"><bounds x="30" y="20" width="10" height="10" /></element>
</group>
<view name="Test">
@@ -902,8 +843,8 @@ elements allowed inside a ``repeat`` element depend on where it appears:
* A repeating block inside the top-level ``mamelayout`` element may contain
``param``, ``element``, ``group`` (definition), and ``repeat`` elements.
* A repeating block inside a ``group`` or ``view`` element may contain
- ``param``, ``backdrop``, ``screen``, ``overlay``, ``bezel``, ``cpanel``,
- ``marquee``, ``group`` (reference), and ``repeat`` elements.
+ ``param``, ``element`` (reference), ``screen``, ``group`` (reference), and
+ ``repeat`` elements.
A repeating block effectively repeats its contents the number of times specified
by its ``count`` attribute. See the relevant sections for details on how the
@@ -928,9 +869,9 @@ element)::
<repeat count="40">
<param name="i" start="0" increment="1" />
<param name="x" start="5" increment="30" />
- <bezel name="digit~i~" element="digit">
+ <element name="digit~i~" ref="digit">
<bounds x="~x~" y="5" width="25" height="50" />
- </bezel>
+ </element>
</repeat>
Eight five-by-seven dot matrix displays in a row, with pixels controlled by
@@ -945,9 +886,9 @@ outputs ``Dot_000`` to ``Dot_764`` (inside a ``group`` or ``view`` element)::
<repeat count="5"> <!-- 5 columns in each digit -->
<param name="colno" start="1" increment="1" />
<param name="colx" start="~digitx~" increment="111" /> <!-- horizontal distance between LEDs -->
- <bezel name="Dot_~digitno~~rowno~~colno~" element="Pixel" state="0">
+ <element name="Dot_~digitno~~rowno~~colno~" ref="Pixel" state="0">
<bounds x="~colx~" y="~rowy~" width="100" height="100" /> <!-- size of each LED -->
- </bezel>
+ </element>
</repeat>
</repeat>
</repeat>
@@ -966,9 +907,9 @@ or ``view`` element)::
<param name="col" start="~group~" increment="1" />
<param name="btnx" start="~padx~" increment="110" />
<param name="mask" start="~mask~" lshift="1" />
- <bezel element="btn~row~~col~" inputtag="row~row~" inputmask="~mask~">
+ <element ref="btn~row~~col~" inputtag="row~row~" inputmask="~mask~">
<bounds x="~btnx~" y="~y~" width="80" height="80" />
- </bezel>
+ </element>
</repeat>
</repeat>
</repeat>
@@ -998,14 +939,14 @@ Generating a chequerboard pattern with alternating alpha values 0.4 and 0.2
<param name="rx" start="13" increment="20" />
<param name="lmask" start="0x01" lshift="2" />
<param name="rmask" start="0x02" lshift="2" />
- <bezel element="hl" inputtag="board:IN.~rowno~" inputmask="~lmask~">
+ <element ref="hl" inputtag="board:IN.~rowno~" inputmask="~lmask~">
<bounds x="~lx~" y="~rowy~" width="10" height="10" />
<color alpha="~lalpha~" />
- </bezel>
- <bezel element="hl" inputtag="board:IN.~rowno~" inputmask="~rmask~">
+ </element>
+ <element ref="hl" inputtag="board:IN.~rowno~" inputmask="~rmask~">
<bounds x="~rx~" y="~rowy~" width="10" height="10" />
<color alpha="~ralpha~" />
- </bezel>
+ </element>
</repeat>
</repeat>
</repeat>