summaryrefslogtreecommitdiffstatshomepage
path: root/docs
diff options
context:
space:
mode:
author Vas Crabb <vas@vastheman.com>2019-07-06 00:23:20 +1000
committer Vas Crabb <vas@vastheman.com>2019-07-06 00:23:20 +1000
commitc38a3395e94e38a37cf6b8efdf9f49a5c9d415df (patch)
tree8ad5f6ee37953b4d19241ce31d11da23a712cc3e /docs
parent7ee50ffec7afabd20a027f89e47f11b116301071 (diff)
Make layout format more flexible:
* There is no longer a concept of "layers" - there are only screens and elements. * Elements are now instantiated with <element ref="..."> * Screens and elements can have explicit blending mode specified with blend="..." * Default blending mode for screens is "add" and default for other elements is "alpha" * Other supported modes are "none" and "multiply" * This removes the options to enable/disable layers individually - use views instead * Legacy layouts can still be loaded, and support won't be removed for at least a year The current artwork model is over-stretched. It's based on a Space Invaders cabinet model, and isn't applicable to a lot of the systems MAME emulates now. The fact that MAME has to switch to an "alternate" mode to deal with games like Golly! Ghost! without requiring pre-matted bitmaps shows that the Space Invaders model wasn't even adequate for general arcade use. It shows in that for a lot of the systems that heavily depend on artwork, people just seem to randomly choose layers for elements until they get something that works. Also, the fact that MAME will switch to an alternate (Golly! Ghost!) mode depending on the combination of elements is a trap for people learning to make artwork. There are cases that the current approach of implying the blending mode from the layer doesn't work with. Examples include LEDs behind diffusers (requires additive blending for layout elements), and mutliple stacked LCD panels (requires RGB multiplication for screens). For configurability, it's now a lot easier to make multiple views using groups. For example, if you want to make it possible to hide the control panel section of your layout, you can put the control panel elements in a group and create views with and without it. I will gradually migrate the internal artwork to use the new approach. I have an XSLT stylesheet that helps with this, but I'm not comfortable adding it because it isn't a complete solution and it still requires manul steps. I wanted to get the re-worked pointer handling done sooner so I could push them both at the same time, but unfortunately various things have prevented me from progressing as quickly as I wanted to. Sorry guys, that stuff's going to have to wait.
Diffstat (limited to 'docs')
-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>