From c38a3395e94e38a37cf6b8efdf9f49a5c9d415df Mon Sep 17 00:00:00 2001 From: Vas Crabb Date: Sat, 6 Jul 2019 00:23:20 +1000 Subject: Make layout format more flexible: * There is no longer a concept of "layers" - there are only screens and elements. * Elements are now instantiated with * 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. --- docs/source/commandline/commandline-all.rst | 40 ----- docs/source/commandline/commandline-index.rst | 5 - docs/source/techspecs/layout_files.rst | 231 ++++++++++---------------- 3 files changed, 86 insertions(+), 190 deletions(-) (limited to 'docs') 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 ` -| :ref:`[no]use_backdrops ` -| :ref:`[no]use_overlays ` -| :ref:`[no]use_bezels ` -| :ref:`[no]use_cpanels ` -| :ref:`[no]use_marquees ` | :ref:`fallback_artwork ` | :ref:`override_artwork ` 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~``:: - + - + 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:: - + + - -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:: - - +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:: + + - - - - + + + + + - - + -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:: - - - - - - + + + + + + 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:: - - + + @@ -850,8 +791,8 @@ positions elements outside its explicit bounds:: - - + + @@ -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):: - + - + 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):: - + - + @@ -966,9 +907,9 @@ or ``view`` element):: - + - + @@ -998,14 +939,14 @@ Generating a chequerboard pattern with alternating alpha values 0.4 and 0.2 - + - - + + - + -- cgit v1.2.3