diff options
Diffstat (limited to 'docs/source/techspecs/layout_files.rst')
-rw-r--r-- | docs/source/techspecs/layout_files.rst | 90 |
1 files changed, 40 insertions, 50 deletions
diff --git a/docs/source/techspecs/layout_files.rst b/docs/source/techspecs/layout_files.rst index c43a7df8e1b..a014756a32b 100644 --- a/docs/source/techspecs/layout_files.rst +++ b/docs/source/techspecs/layout_files.rst @@ -396,8 +396,8 @@ Elements ~~~~~~~~ Elements are one of the basic visual objects that may be arranged, along with -screens, to make up a view. Elements may be built up one or more *components*, -but an element is treated as as single surface when building the scene graph +screens, to make up a view. Elements may be built up of one or more *components*, +but an element is treated as a single surface when building the scene graph and rendering. An element may be used in multiple views, and may be used multiple times within a view. @@ -497,15 +497,15 @@ image human-readable SVG graphics. A ``file`` attribute or ``data`` child element must be supplied; it is an error if neither or both are supplied. - If the ``alphafile`` attribute refers refers to a file, it must have the - same dimensions (in pixels) as the file referred to by the ``file`` - attribute, and must have a bit depth no greater than eight bits per channel - per pixel. The intensity from this image (brightness) is copied to the - alpha channel, with full intensity (white in a greyscale image) - corresponding to fully opaque, and black corresponding to fully transparent. - The ``alphafile`` attribute will be ignored if the ``file`` attribute refers - to an SVG image or the ``data`` child element contains SVG data; it is only - used in conjunction with bitmap images. + If the ``alphafile`` attribute refers to a file, it must have the same + dimensions (in pixels) as the file referred to by the ``file`` attribute, + and must have a bit depth no greater than eight bits per channel per pixel. + The intensity from this image (brightness) is copied to the alpha channel, + with full intensity (white in a greyscale image) corresponding to fully + opaque, and black corresponding to fully transparent. The ``alphafile`` + attribute will be ignored if the ``file`` attribute refers to an SVG image + or the ``data`` child element contains SVG data; it is only used in + conjunction with bitmap images. The image file(s) should be placed in the same directory/archive as the layout file. Image file formats are detected by examining the content of @@ -517,21 +517,6 @@ text be an integer, where 0 (zero) means centred, 1 (one) means left-aligned, and 2 (two) means right-aligned. If the ``align`` attribute is absent, the text will be centred. -dotmatrix - Draws an eight-pixel horizontal segment of a dot matrix display, using - circular pixels in the specified colour. The bits of the element’s state - determine which pixels are lit, with the least significant bit corresponding - to the leftmost pixel. Unlit pixels are drawn at low intensity (0x20/0xff). -dotmatrix5dot - Draws a five-pixel horizontal segment of a dot matrix display, using - circular pixels in the specified colour. The bits of the element’s state - determine which pixels are lit, with the least significant bit corresponding - to the leftmost pixel. Unlit pixels are drawn at low intensity (0x20/0xff). -dotmatrixdot - Draws a single element of a dot matrix display as a circular pixels in the - specified colour. The least significant bit of the element’s state - determines whether the pixel is lit. An unlit pixel is drawn at low - intensity (0x20/0xff). led7seg Draws a standard seven-segment (plus decimal point) digital LED/fluorescent display in the specified colour. The low eight bits of the element’s state @@ -539,14 +524,6 @@ led7seg the bits correspond to the top segment, the upper right-hand segment, continuing clockwise to the upper left segment, the middle bar, and the decimal point. Unlit segments are drawn at low intensity (0x20/0xff). -led8seg_gts1 - Draws an eight-segment digital fluorescent display of the type used in - Gottlieb System 1 pinball machines (actually a Futaba part). Compared to - standard seven-segment displays, these displays have no decimal point, the - horizontal middle bar is broken in the centre, and there is a broken - vertical middle bar controlled by the bit that would control the decimal - point in a standard seven-segment display. Unlit segments are drawn at low - intensity (0x20/0xff). led14seg Draws a standard fourteen-segment alphanumeric LED/fluorescent display in the specified colour. The low fourteen bits of the element’s state control @@ -713,6 +690,11 @@ element. This means a view can reference elements and groups that appear after it in the file, and parameters from the enclosing scope will have their final values from the end of the ``mamelayout`` element. +A ``view`` element may have a ``showpointers`` attribute to set whether mouse +and pen pointers should be shown for the view. If present, the value must be +either ``yes`` or ``no``. If the ``showpointers`` attribute is not present, pen +and mouse pointers are shown for views that contain items bound to I/O ports. + The following child elements are allowed inside a ``view`` element: bounds @@ -754,7 +736,7 @@ screen collection Adds screens and/or items in a collection that can be shown or hidden by the user (see :ref:`layfile-parts-collections`). The name of the collection is - specified using the required ``name`` attribute.. There is a limit of 32 + specified using the required ``name`` attribute. There is a limit of 32 collections per view. group Adds the content of the group to the view (see :ref:`layfile-parts-groups`). @@ -1211,7 +1193,7 @@ Clickable items If a view item (``element`` or ``screen`` element) has ``inputtag`` and ``inputmask`` attribute values that correspond to a digital switch field in the emulated system, clicking the element will activate the switch. The switch -will remain active as long as the mouse button is held down and the pointer is +will remain active as long as the primary button is held down and the pointer is within the item’s current bounds. (Note that the bounds may change depending on the item’s animation state, see :ref:`layfile-interact-itemanim`). @@ -1220,6 +1202,12 @@ device that caused the layout file to be loaded. The ``inputmask`` attribute must be an integer specifying the bits of the I/O port field that the item should activate. This sample shows instantiation of clickable buttons: +The ``clickthrough`` attribute controls whether clicks can pass through the view +item to other view items drawn above it. The ``clickthrough`` attribute must be +``yes`` or ``no`` if present. The default is ``no`` (clicks do not pass +through) for view items with ``inputtag`` and ``inputmask`` attributes, and +``yes`` (clicks pass through) for other view items. + .. code-block:: XML <element ref="btn_3" inputtag="X2" inputmask="0x10"> @@ -1232,9 +1220,8 @@ should activate. This sample shows instantiation of clickable buttons: <bounds x="1.775" y="5.375" width="1.0" height="1.0" /> </element> -When handling mouse input, MAME treats all layout elements as being rectangular, -and only activates the first clickable item whose area includes the location of -the mouse pointer. +When handling pointer input, MAME treats all layout elements as being +rectangular. .. _layfile-interact-elemstate: @@ -1292,7 +1279,7 @@ View item animation Items’ colour and position/size within their containing view may be animated. This is achieved by supplying multiple ``color`` and/or ``bounds`` child elements with ``state`` attributes. The ``state`` attribute of each ``color`` -or ``bounds`` child element must be a non-negative integer. Withing a view +or ``bounds`` child element must be a non-negative integer. Within a view item, no two ``color`` elements may have equal state ``state`` attributes, and no two ``bounds`` elements may have equal ``state`` attributes. @@ -1484,33 +1471,36 @@ Example layout files These layout files demonstrate various artwork system features. They are all internal layouts included in MAME. -`sstrangr.lay <https://git.redump.net/mame/tree/src/mame/layout/sstrangr.lay?h=mame0235>`_ +`sstrangr.lay <https://git.redump.net/mame/tree/src/mame/layout/sstrangr.lay?h=mame0261>`_ A simple case of using translucent colour overlays to visually separate and highlight elements on a black and white screen. -`seawolf.lay <https://git.redump.net/mame/tree/src/mame/layout/seawolf.lay?h=mame0235>`_ +`seawolf.lay <https://git.redump.net/mame/tree/src/mame/layout/seawolf.lay?h=mame0261>`_ This system uses lamps for key gameplay elements. Blending modes are used for the translucent colour overlay placed over the monitor, and the lamps reflected in front of the monitor. Also uses collections to allow parts of - the layout to be disabled selectively. The shapes on the overlay are drawn - using embedded SVG images. -`armora.lay <https://git.redump.net/mame/tree/src/mame/layout/armora.lay?h=mame0235>`_ + the layout to be disabled selectively. +`armora.lay <https://git.redump.net/mame/tree/src/mame/layout/armora.lay?h=mame0261>`_ This game’s monitor is viewed directly through a translucent colour overlay rather than being reflected from inside the cabinet. This means the overlay reflects ambient light as well as affecting the colour of the video image. -`tranz330.lay <https://git.redump.net/mame/tree/src/mame/layout/tranz330.lay?h=mame0235>`_ + The shapes on the overlay are drawn using embedded SVG images. +`tranz330.lay <https://git.redump.net/mame/tree/src/mame/layout/tranz330.lay?h=mame0261>`_ A multi-segment alphanumeric display and keypad. The keys are clickable, and provide visual feedback when pressed. -`esq2by16.lay <https://git.redump.net/mame/tree/src/mame/layout/esq2by16.lay?h=mame0235>`_ +`esq2by16.lay <https://git.redump.net/mame/tree/src/mame/layout/esq2by16.lay?h=mame0261>`_ Builds up a multi-line dot matrix character display. Repeats are used to avoid repetition for the rows in a character, characters in a line, and lines in a page. Group colors allow a single element to be used for all four display colours. -`cgang.lay <https://git.redump.net/mame/tree/src/mame/layout/cgang.lay?h=mame0235>`_ +`cgang.lay <https://git.redump.net/mame/tree/src/mame/layout/cgang.lay?h=mame0261>`_ Animates the position of element items to simulate an electromechanical shooting gallery game. Also demonstrates effective use of components to build up complex graphics. -`unkeinv.lay <https://git.redump.net/mame/tree/src/mame/layout/unkeinv.lay?h=mame0235>`_ +`minspace.lay <https://git.redump.net/mame/tree/src/mame/layout/minspace.lay?h=mame0261>`_ Shows the position of a slider control with LEDs on it. -`md6802.lay <https://git.redump.net/mame/tree/src/mame/layout/md6802.lay?h=mame0235>`_ +`md6802.lay <https://git.redump.net/mame/tree/src/mame/layout/md6802.lay?h=mame0261>`_ Effectively using groups as a procedural programming language to build up an image of a trainer board. +`beena.lay <https://git.redump.net/mame/tree/src/mame/layout/beena.lay?h=mame0261>`_ + Using event-based scripting to dynamically position elements and draw elemnt + content programmatically. |