diff options
author | 2018-07-31 04:18:28 +1000 | |
---|---|---|
committer | 2018-07-31 04:18:28 +1000 | |
commit | 0ce07a8a1e5e5787917435037c326c7bd67adbc7 (patch) | |
tree | b958b89a366a2f923535d066cd45ce29f4339d7c /docs | |
parent | 1a899d987f40730c839f8adf719d18a0789062e9 (diff) |
(nw) more render work:
* Clean up some corner cases in layouts with repeating blocks
* Make complay.py validate many more elements and attributes
* Make complay.py easier to use for just validating a layout
* Remove redundant view from Sega VMU layout
* Make buttons visually respond to input in whousetc.lay
* Add view with LED displays as well as terminal for aim65_40 and use repeats
* Clean up some outdated "game" terminology in clifront.cpp
* Initiaise a couple of members in tap/tun network module
* Start documenting layout format
Diffstat (limited to 'docs')
-rw-r--r-- | docs/source/techspecs/index.rst | 1 | ||||
-rw-r--r-- | docs/source/techspecs/layout_files.rst | 615 |
2 files changed, 616 insertions, 0 deletions
diff --git a/docs/source/techspecs/index.rst b/docs/source/techspecs/index.rst index 6ed4435772a..67775ae3a74 100644 --- a/docs/source/techspecs/index.rst +++ b/docs/source/techspecs/index.rst @@ -6,6 +6,7 @@ This section covers technical specifications useful to programmers working on MA .. toctree:: :titlesonly: + layout_files device_memory_interface device_rom_interface device_disasm_interface diff --git a/docs/source/techspecs/layout_files.rst b/docs/source/techspecs/layout_files.rst new file mode 100644 index 00000000000..91796700342 --- /dev/null +++ b/docs/source/techspecs/layout_files.rst @@ -0,0 +1,615 @@ +MAME Layout Files +================= + +.. contents:: :local: + + +.. _layout-intro: + +Introduction +------------ + +Layout files are used to tell MAME what to display when running an emulated +system, and how to arrange it. MAME can render emulated screens, images, text, +shapes, and specialised objects for common output devices. Elements can be +static, or dynamically update to reflect the state of inputs and outputs. +Layouts may be automatically generated based on the number/type of emulated +screens, built and linked into the MAME binary, or provided externally. MAME +layout files are an XML application, using the ``.lay`` filename extension. + + +.. _layout-concepts: + +Core concepts +------------- + +.. _layout-concepts-numbers: + +Numbers +~~~~~~~ + +There are two kinds of numbers in MAME layouts: integers and floating-point +numbers. + +Integers may be supplied in decimal or hexadecimal notation. A decimal integer +consists of and optional # (hash) prefix, an optional +/- (plus or minus) sign +character, and a sequence of digits 0-9. A hexadecimal number consists of one +of the prefixes $ (dollar sign) or 0x (zero ex) followed by a sequence of +hexadecimal digits 0-9 and A-F. Hexadecimal numbers are case-insensitive for +both the prefix and digits. + +Floating-point numbers may be supplied in decimal fixed-point or scientific +notation. Note that integer prefixes and hexadecimal values are *not* +accepted where a floating-point number is expected. + +For a few attributes, both integers and floating-point numbers are allowed. In +these cases, the presence of a # (hash), $ (dollar sign) or 0x (zero ex) prefix +causes the value to be interpreted as an integer. If no recognised integer +prefix is found and the value contains a decimal point or the letter E +(uppercase or lowercase) introducing an exponent, it is interpreted as a +floating-point number. If no integer prefix, decimal point or letter E is +found, the number will be interpreted as an integer. + +Numbers are parsed using the "C" locale for portability. + + +.. _layout-concepts-coordinates: + +Coordinates +~~~~~~~~~~~ + +Layout coordinates are internally represented as IEEE754 32-bit binary +floating-point numbers (also known as "single precision"). Coordinates increase +in the rightward and downward directions. The origin (0,0) has no particular +significance, and you may freely use negative coordinates in layouts. +Coordinates are supplied as floating-point numbers. + +MAME assumes that view coordinates have the same aspect ratio as pixel on the +output device (host screen or window). Assuming square pixels and no rotation, +this means equal distances in X and Y axes correspond to equal horizontal and +vertical distances in the rendered output. + +Views, groups and elements all have their own internal coordinate systems. When +an element or group is referenced from a view or another group, its coordinates +are scaled as necessary to fit the specified bounds. + +Objects are positioned and sized using ``bounds`` elements. A bounds element +may specify the position of the top left corner and the size using ``x``, ``y``, +``width`` and ``height`` attributes, or it may specify the coordinates of the +edges with the ``left``, ``top``, ``right`` and ``bottom`` attributes. These +two ``bounds`` elements are equivalent:: + + <bounds x="455" y="120" width="11" height="7" /> + <bounds left="455" top="120" right="466" bottom="127" /> + +Either the ``x`` or ``left`` attribute must be present to distinguish between +the two schemes. The ``width`` and ``height`` or ``right`` and ``bottom`` +default to 1.0 if not supplied. It is an error if ``width`` or ``height`` are +negative, if ``right`` is less than ``left``, or if ``bottom`` is less than +``top``. + + +.. _layout-concepts-colours: + +Colours +~~~~~~~ + +Colours are specified in RGBA space. MAME is not aware of colour profiles and +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). + +Component and view item colour is specified using ``color`` elements. +Meaningful attributes are ``red``, ``green``, ``blue`` and ``alpha``. This +example ``color`` element specifies all channel values:: + + <color red="0.85" green="0.4" blue="0.3" alpha="1.0" /> + +Any omitted channel attributes default to 1.0 (full intensity or opaque). It +is an error if any channel value falls outside the range of 0.0 to 1.0 +(inclusive). + + +.. _layout-concepts-params: + +Parameters +~~~~~~~~~~ + +Parameters are named variables that can be used in most attributes. To use +a parameter in an attribute, surround its name with tilde (~) characters. If a +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"> + <bounds x="~x~" y="80" width="25" height="40" /> + </bezel> + +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. +Parameter names are case-sensitive. When looking for a parameter, the layout +engine starts at the current, innermost scope and works outwards. The outermost +scope level corresponds to the top-level ``mamelayout`` element. Each +``repeat``, ``group`` or ``view`` element creates a new, nested scope level. + +Internally a parameter can hold a string, integer, or floating-point number, but +this is mostly transparent. Integers are stored as 64-bit signed +twos-complement values, and floating-point numbers are stored as IEEE754 64-bit +binary floating-point numbers (also known as "double precision"). Integers are +substituted in decimal notation, and floating point numbers are substituted in +default format, which may be decimal fixed-point or scientific notation +depending on the value). There is no way to override the default formatting of +integer and floating-point number parameters. + +There are two kinds of parameters: *value parameters* and *generator +parameters*. Value parameters keep their assigned value until reassigned. +Generator parameters have a starting value and an increment and/or shift to be +applied for each iteration. + +Value parameters are assigned using a ``param`` element with ``name`` and +``value`` attributes. Value parameters may appear inside the top-level +``mamelayout`` element, inside ``repeat``, and ``view`` elements, and inside +``group`` definition elements (that is, ``group`` elements in the top-level +``mamelayout`` element, as opposed to ``group`` reference elements inside +``view`` elements other ``group`` definition elements). A value parameter may +be reassigned at any point. + +Here's an example assigning the value "4" to the value parameter "firstdigit":: + + <param name="firstdigit" value="4" /> + +Generator parameters are assigned using a ``param`` element with ``name`` and +``start`` attributes, and ``increment``, ``lshift`` and/or ``rshift`` +attributes. Generator parameters may only appear inside ``repeat`` elements. +A generator parameter must not be reassigned in the same scope (an identically +named parameter may be defined in a child scope). Here are some example +generator parameters:: + + <param name="nybble" start="3" increment="-1" /> + <param name="switchpos" start="74" increment="156" /> + <param name="mask" start="0x0800" rshift="4" /> + +* The ``nybble`` parameter generates values 3, 2, 1... +* The ``switchpos`` parameter generates values 74, 230, 386... +* The ``mask`` parameter generates values 2048, 1024, 512... + +The ``increment`` attribute must be an integer or floating-point number to be +added to the parameter's value. The ``lshift`` and ``rshift`` attributes must +be non-negative integers specifying numbers of bits to shift the parameter's +value to the left or right. The increment and shift are applied at the end of +the repeating block before the next iteration starts. If both an increment and +shift are supplied, the increment is applied before the shift. + +If the ``increment`` attribute is present and is a floating-point number, the +parameter's value will be interpreted as an integer or floating-point number and +converted to a floating-point number before the increment is added. If the +``increment`` attribute is present and is an integer, the parameter's value will +be interpreted as an integer or floating number before the increment is added. +The increment will be converted to a floating-point number before the addition +if the parameter's value is a floating-point number. + +If the ``lshift`` and/or ``rshift`` attributes are present and not equal, the +parameter's value will be interpreted as an integer or floating-point number, +converted to an integer as necessary, and shifted accordingly. Shifting to the +left is defined as shifting towards the most significant bit. If both +``lshift`` and ``rshift`` are supplied, they are netted off before being +applied. This means you cannot, for example, use equal ``lshift`` and +``rshift`` attributes to clear bits at one end of a parameter's value after the +first iteration. + +It is an error if a ``param`` element has neither ``value`` nor ``start`` +attributes, and it is an error if a ``param`` element has both a ``value`` +attribute and any of the ``start``, ``increment``, ``lshift``, or ``rshift`` +attributes. + +A ``param`` element defines a parameter or reassigns its value in the current, +innermost scope. It is not possible to define or reassign parameters in a +containing scope. + + +.. _layout-concepts-predef-params: + +Pre-defined parameters +~~~~~~~~~~~~~~~~~~~~~~ + +A number of pre-defined value parameters are available providing information +about the running machine: + +devicetag + The full tag path of the device that caused the layout to be loaded, for + example ``:`` for the root driver device, or ``:tty:ie15`` for a terminal + connected to a port. This parameter is a string defined at layout (global) + scope. +devicebasetag + The base tag of the device that caused the layout to be loaded, for example + ``root`` for the root driver device, or ``ie15`` for a terminal connected to + a port. This parameter is a string defined at layout (global) scope. +devicename + The full name (description) of the device that caused the layout to be + loaded, for example ``AIM-65/40`` or ``IE15 Terminal``. This parameter is a + string defined at layout (global) scope. +deviceshortname + The short name of the device that caused the layout to be loaded, for + example ``aim65_40`` or ``ie15_terminal``. This parameter is a string + defined at layout (global) scope. +scr0physicalxaspect + The horizontal part of the physical aspect ratio of the first screen (if + present). The physical aspect ratio is provided as a reduced improper + fraction. Note that this is the horizontal component *before* rotation is + applied. This parameter is an integer defined at layout (global) scope. +scr0physicalyaspect + The vertical part of the physical aspect ratio of the first screen (if + present). The physical aspect ratio is provided as a reduced improper + fraction. Note that this is the vertical component *before* rotation is + applied. This parameter is an integer defined at layout (global) scope. +scr0nativexaspect + The horizontal part of the pixel aspect ratio of the first screen's visible + area (if present). The pixel aspect ratio is provided as a reduced improper + fraction. Note that this is the horizontal component *before* rotation is + applied. This parameter is an integer defined at layout (global) scope. +scr0nativeyaspect + The vertical part of the pixel aspect ratio of the first screen's visible + area (if present). The pixel aspect ratio is provided as a reduced improper + fraction. Note that this is the vertical component *before* rotation is + applied. This parameter is an integer defined at layout (global) scope. +scr0width + The width of the first screen's visible area (if present) in emulated + pixels. Note that this is the width *before* rotation is applied. This + parameter is an integer defined at layout (global) scope. +scr0height + The height of the first screen's visible area (if present) in emulated + pixels. Note that this is the height *before* rotation is applied. This + parameter is an integer defined at layout (global) scope. +scr1physicalxaspect + The horizontal part of the physical aspect ratio of the second screen (if + present). This parameter is an integer defined at layout (global) scope. +scr1physicalyaspect + The vertical part of the physical aspect ratio of the second screen (if + present). This parameter is an integer defined at layout (global) scope. +scr1nativexaspect + The horizontal part of the pixel aspect ratio of the second screen's visible + area (if present). This parameter is an integer defined at layout (global) + scope. +scr1nativeyaspect + The vertical part of the pixel aspect ratio of the second screen's visible + area (if present). This parameter is an integer defined at layout (global) + scope. +scr1width + The width of the second screen's visible area (if present) in emulated + pixels. This parameter is an integer defined at layout (global) scope. +scr1height + The height of the second screen's visible area (if present) in emulated + pixels. This parameter is an integer defined at layout (global) scope. +scr\ *N*\ physicalxaspect + The horizontal part of the physical aspect ratio of the (zero-based) *N*\ th + screen (if present). This parameter is an integer defined at layout + (global) scope. +scr\ *N*\ physicalyaspect + The vertical part of the physical aspect ratio of the (zero-based) *N*\ th + screen (if present). This parameter is an integer defined at layout + (global) scope. +scr\ *N*\ nativexaspect + The horizontal part of the pixel aspect ratio of the (zero-based) *N*\ th + screen's visible area (if present). This parameter is an integer defined at + layout (global) scope. +scr\ *N*\ nativeyaspect + The vertical part of the pixel aspect ratio of the (zero-based) *N*\ th + screen's visible area (if present). This parameter is an integer defined at + layout (global) scope. +scr\ *N*\ width + The width of the (zero-based) *N*\ th screen's visible area (if present) in + emulated pixels. This parameter is an integer defined at layout (global) + scope. +scr\ *N*\ height + The height of the (zero-based) *N*\ th screen's visible area (if present) in + emulated pixels. This parameter is an integer defined at layout (global) + scope. +viewname + The name of the current view. This parameter is a string defined at view + scope. It is not defined outside a view. + +For screen-related parameters, screens are numbered from zero in the order they +appear in machine configuration, and all screens are included (not just +subdevices of the device that caused the layout to be loaded). X/width and +Y/height refer to the horizontal and vertical dimensions of the screen *before* +rotation is applied. Values based on the visible area are calculated at the +end of configuration. Values are not updated and layouts are not recomputed if +the system reconfigures the screen while running. + + +.. _layout-parts: + +Parts of a layout +----------------- + +A *view* specifies an arrangement graphical object to display. A MAME layout +file can contain multiple views. Views are built up from *elements* and +*screens*. To simplify complex layouts, reusable groups and repeating blocks +are supported. + +The top-level element of a MAME layout file must be a ``mamelayout`` element +with a ``version`` attribute. The ``version`` attribute must be an integer. +Currently MAME only supports version 2, and will not load any other version. +This is an example opening tag for a top-level ``mamelayout`` element:: + + <mamelayout version="2"> + +In general, children of the top-level ``mamelayout`` element are processed in +reading order from top to bottom. The exception is that, for historical +reasons, views are processed last. This means views see the final values of all +parameters at the end of the ``mamelayout`` element, and may refer to elements +and groups that appear after them. + +The following elements are allowed inside the top-level ``mamelayout`` element: + +param + Defines or reassigns a value parameter. See :ref:`layout-concepts-params` + for details. +element + Defines an element -- one of the basic objects that can be arranged in a + view. See :ref:`layout-parts-elements` for details. +group + Defines a reusable group of elements/screens that may be referenced from + views or other groups. See :ref:`layout-parts-groups` for details. +repeat + A repeating group of elements -- may contain ``param``, ``element``, + ``group``, and ``repeat`` elements. See :ref:`layout-parts-repeats` for + details. +view + An arrangement of elements and/or screens that can be displayed on an output + device (a host screen/window). See :ref:`layout-parts-views` for details. +script + Allows lua script to be supplied for enhanced interactive layouts. + + +.. _layout-parts-elements: + +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 +and rendering. An element may be used in multiple views, and may be used +multiple times within a view. + +An element's appearance depends on its *state*. The state is an integer which +usually comes from an I/O port field or an emulated output (see the discussion +of :ref:`layout-parts-views` for information on connecting an element to an I/O +port or output). Any component of an element may be restricted to only drawing +when the element's state is a particular value. Some components (e.g. +multi-segment displays and reels) use the state directly to determine their +appearance. + +Each element has its own internal coordinate system. The bounds of the +element's coordinate system are computed as the union of the bounds of the +individual components it's composed of. + +Every element must have a ``name`` attribute specifying its name. Elements are +referred to by name when instantiated in groups or views. Elements may +optionally supply a default state value with a ``defstate`` attribute, to be +used if not connected to an emulated output or I/O port. If present, the +``defstate`` attribute must be a non-negative integer. + +Child elements of the ``element`` element instantiate components, which are +drawn in reading order from first to last (components draw on top of components +that come before them). All components support a few common features: + +* Each component may have a ``state`` attribute. If present, the component will + only be drawn when the element's state matches its value (if absent, the + component will always be drawn). If present, the ``state`` attribute must be + a non-negative integer. +* Each component may have a ``bounds`` child element specifying its position and + size (see :ref:`layout-concepts-coordinates`). If no such element is present, + the bounds default to a unit square (width and height of 1.0) with the top + left corner at (0,0). +* Each component may have a ``color`` child element specifying an RGBA colour + (see :ref:`layout-concepts-colours` for details). This can be used to control + the colour of geometric, algorithmically drawn, or textual components. It is + ignored for ``image`` components. If no such element is present, the colour + defaults to opaque white. + +The following components are supported: + +rect + Draws a uniform colour rectangle filling its bounds. +disk + Draws a uniform colour ellipse fitted to its bounds. +image + Draws an image loaded from a PNG or JPEG file. The name of the file to load + (including the file name extension) is supplied with the required ``file`` + attribute. Additionally, an optional ``alphafile`` attribute may be used to + specify the name of a PNG file (including the file name extension) to load + into the alpha channel of the image. The image file(s) should be placed in + the same directory/archive as the layout file. If the ``alphafile`` + attribute refers refers to a file, it must have the same dimensions 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. +text + Draws text in using the UI font in the specified colour. The text to draw + must be supplied using a ``string`` attribute. An ``align`` attribute may + be supplied to set text alignment. If present, the ``align`` attribute must + 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 + control which segments are lit. Starting from the least significant bit, + 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 + which segments are lit. Starting from the least significant bit, the bits + correspond to the top segment, the upper right-hand segment, continuing + clockwise to the upper left segment, the left-hand and right-hand halves of + the horizontal middle bar, the upper and lower halves of the vertical middle + bar, and the diagonal bars clockwise from lower left to lower right. Unlit + segments are drawn at low intensity (0x20/0xff). +led14segsc + Draws a standard fourteen-segment alphanumeric LED/fluorescent display with + decimal point/comma in the specified colour. The low sixteen bits of the + element's state control which segments are lit. The low fourteen bits + correspond to the same segments as in the ``led14seg`` component. Two + additional bits correspond to the decimal point and comma tail. Unlit + segments are drawn at low intensity (0x20/0xff). +led16seg + Draws a standard sixteen-segment alphanumeric LED/fluorescent display in the + specified colour. The low sixteen bits of the element's state control which + segments are lit. Starting from the least significant bit, the bits + correspond to the left-hand half of the top bar, the right-hand half of the + top bar, continuing clockwise to the upper left segment, the left-hand and + right-hand halves of the horizontal middle bar, the upper and lower halves + of the vertical middle bar, and the diagonal bars clockwise from lower left + to lower right. Unlit segments are drawn at low intensity (0x20/0xff). +led16segsc + Draws a standard sixteen-segment alphanumeric LED/fluorescent display with + decimal point/comma in the specified colour. The low eighteen bits of the + element's state control which segments are lit. The low sixteen bits + correspond to the same segments as in the ``led16seg`` component. Two + additional bits correspond to the decimal point and comma tail. Unlit + segments are drawn at low intensity (0x20/0xff). +simplecounter + Displays the numeric value of the element's state using the system font in + the specified colour. The value is formatted in decimal notation. A + ``digits`` attribute may be supplied to specify the minimum number of digits + to display. If present, the ``digits`` attribute must be a positive + integer; if absent, a minimum of two digits will be displayed. A + ``maxstate`` attribute may be supplied to specify the maximum state value to + display. If present, the ``maxstate`` attribute must be a non-negative + number; if absent it defaults to 999. An ``align`` attribute may be supplied + to set text alignment. If present, the ``align`` attribute must be an + integer, where 0 (zero) means centred, 1 (one) means left-aligned, and 2 + (two) means right-aligned; if absent, the text will be centred. +reel + Used for drawing slot machine reels. Supported attributes include + ``symbollist``, ``stateoffset``, ``numsymbolsvisible``, ``reelreversed``, + and ``beltreel``. + +An example element that draws a static left-aligned text string:: + + <element name="label_reset_cpu"> + <text string="CPU" align="1"><color red="1.0" green="1.0" blue="1.0" /></text> + </element> + + +An example element that displays a circular LED where the intensity depends on +the state of an active-high output:: + + <element name="led" defstate="0"> + <rect state="0"><color red="0.43" green="0.35" blue="0.39" /></rect> + <rect state="1"><color red="1.0" green="0.18" blue="0.20" /></rect> + </element> + +An example element for a button that gives visual feedback when clicked:: + + <element name="btn_rst"> + <rect state="0"><bounds x="0.0" y="0.0" width="1.0" height="1.0" /><color red="0.2" green="0.2" blue="0.2" /></rect> + <rect state="1"><bounds x="0.0" y="0.0" width="1.0" height="1.0" /><color red="0.1" green="0.1" blue="0.1" /></rect> + <rect state="0"><bounds x="0.1" y="0.1" width="0.9" height="0.9" /><color red="0.1" green="0.1" blue="0.1" /></rect> + <rect state="1"><bounds x="0.1" y="0.1" width="0.9" height="0.9" /><color red="0.2" green="0.2" blue="0.2" /></rect> + <rect><bounds x="0.1" y="0.1" width="0.8" height="0.8" /><color red="0.15" green="0.15" blue="0.15" /></rect> + <text string="RESET"><bounds x="0.1" y="0.4" width="0.8" height="0.2" /><color red="1.0" green="1.0" blue="1.0" /></text> + </element> + + + +.. _layout-autogen: + +Automatically-generated views +----------------------------- + +After loading internal (developer-supplied) and external (user-supplied) +layouts, MAME automatically generates views based on the machine configuration. +The following views will be automatically generated: + +* If the system has no screens and no viable views were found in the internal + and external layouts, MAME will load a view that shows the message "No screens + attached to the system". +* For each emulated screen, MAME will generate a view showing the screen at its + physical aspect ratio with rotation applied. +* For each emulated screen where the configured pixel aspect ratio doesn't match + the physical aspect ratio, MAME will generate a view showing the screen at an + aspect ratio that produces square pixels, with rotation applied. +* If the system has a single emulated screen, MAME will generate a view showing + two copies of the screen image above each other with a small gap between them. + The upper copy will be rotated by 180 degrees. This view can be used in a + "cocktail table" cabinet for simultaneous two-player games, or alternating + play games that don't automatically rotate the display for the second player. + The screen will be displayed at its physical aspect ratio, with rotation + applied. +* If the system has exactly two emulated screens and no view in the internal or + external layouts shows all screens, or if the system has more than two + emulated screens, MAME will generate views with the screens arranged + horizontally from left to right and vertically from top to bottom, both with + and without small gaps between them. The screens will be displayed at + physical aspect ratio, with rotation applied. +* If the system has three or more emulated screens, MAME will generate views + tiling the screens in grid patterns, in both row-major (left-to-right then + top-to-bottom) and column-major (top-to-bottom then left-to-right) order. + Views are generated with and without gaps between the screens. The screens + will be displayed at physical aspect ratio, with rotation applied. + + +.. _layout-complay: + +Using complay.py +---------------- + +The MAME source contains a Python script called ``complay.py``, found in the +``scripts/build`` subdirectory. This script is used as part of MAME's build +process to reduce the size of data for internal layouts and convert it to a form +that can be built into the executable. However, it can also detect many common +layout file format errors, and generally provides better error messages than +MAME does when loading a layout file. Note that it doesn't actually run the +whole layout engine, so it can't detect errors like undefined element references +when parameters are used, or recursively nested groups. The ``complay.py`` +script is compatible with both Python 2.7 and Python 3 interpreters. + +The ``complay.py`` script takes three parameters -- an input file name, an +output file name, and a base name for variables in the output:: + + python scripts/build/complay.py input [output [varname]] + +The input file name is required. If no output file name is supplied, +``complay.py`` will parse and check the input, reporting any errors found, +without producing output. If no base variable name is provided, ``complay.py`` +will generate one based on the input file name. This is not guaranteed to +produce valid identifiers. The exit status is 0 (zero) on success, 1 on an +error in the command invocation, 2 if error are found in the input file, or 3 +in case of an I/O error. If an output file name is specified, the file will be +created/overwritten on success or removed on failure. + +To check a layout file for common errors, run the script with the path to the +file no check and no output file name or base variable name. For example:: + + python scripts/build/complay.py artwork/dino/default.lay |