Layouts and Rendering for MAME Artwork System

From MAMEDEV Wiki

MAME 0.106u2 introduced a major change that needs a more detailed description, the concept of layouts and views.

As a simplistic explanation, layouts are the replacement for the artwork description files (.art) that were previously used to describe artwork to be displayed with a game. However, layouts are much more flexible and much more deeply integrated into the rendering system than the artwork files ever were. You literally can't run the new renderer without a layout loaded.

A layout consists of two parts: a list of zero or more element definitions, and a list of one or more views. The elements represent a sort of library of artwork pieces that can be assembled in various ways. The views represent the actual positioning of these elements relative to the system screens. The easiest way to understand this is to look at the simplest example, which is the default layout used for regular horizontal 4:3 screens:

<?xml version="1.0"?>
<mamelayout version="2">
    <view name="Standard">
        <screen index="0">
            <bounds left="0" top="0" right="4" bottom="3" />
        </screen>
    </view>
</mamelayout>

This particular layout has no elements described, and only a single view. The name of the view is “Standard”. This is important because there is a menu in the UI that lets you select on-the-fly which view to display, and this is the name that is displayed in that menu. Within the view, there can be a two kinds of items:

  • elements specify the attributes of elements defined in the layout XML data.
  • screens specify the attributes of the various screens that make up a game; they are referenced by index or tag.

Everything in the new system is rendered back-to-front, in the order specified in the layout XML data.

Looking back at the example, you can see that a single item has been specified for our view, which is screen index 0 (this will be the first screen in the system). Within the item are some parameters that describe the bounds of the screen within the view. You'll notice that the width of the screen is 4 and the height is 3, this is a fairly arbitrary coordinate system. The layout system will read all the items described, and compute the outer bounds of all of the rectangles specified. It will then scale that to fit whatever screen you have configured. Thus, you can specify your coordinates in pixels or whatever is most convenient. The key here is that the screen as described is a standard 4:3 aspect ratio screen oriented horizontally.

Now, if you're familiar with the old artwork system, you may be scratching your head and thinking, why do we have to specify the aspect ratio of the screen? In the old system, the screen was always positioned from (0,0)-(1,1) and the aspect ratio of the screen (and the resulting artwork) was determined by flags in the game. This is true, and in retrospect, was a mistake. Not only did it make things confusing for positioning purposes, but it meant a lot of the artwork needed to be rotated and tweaked so that it stretched correctly. In addition, in the new world, there is nothing preventing you from having one screen rotated vertically and a second screen rotated horizontally, all within the same view (and yes, there is at least one dual-monitor game that is set up that way).

The next obvious question is, so are we going to need files for all these layouts, even the standard ones? The answer is no. The layout system will load a number of layouts from different sources, and offer you the option of switching between all of the views specified by all of the interesting layouts. The search order is:

  1. Explicitly-specified override files (on the command line or in INI files)
  2. systemname (if not overridden)
  3. System- and device-specific built-in layouts (if not overridden)
  4. parentname (if not overridden and artwork for systemname was not found)
  5. biosname (if not overridden)
  6. Explicitly-specified fallback files (on the command line or in INI files, only if no system artwork has been found yet)
  7. Automatically generated layouts depending on number of screens

The key are the built-in and automatically generated layouts. First, each system can specify a built-in layout as a parameter to the new GAMEL macro, which mimics the existing GAME macro but takes a final parameter that references the system-specific built-in layout, and any device or system can specify a built-in layout in its machine configuration.

Second, MAME automatically generates a number of layouts. By default, each screen in the system gets a Standard layout, which is simply a single screen displayed at its appropriate aspect ratio. Each screen in the system that doesn’t have square pixels also gets a Pixel Aspect layout, which is a single screen displayed 1:1 with the height/width ratio of the pixels. This can be useful for testing purposes. Multi-screen systems get additional options for displaying all screens in a row, column or grid. And finally, just for kicks, single-screen and dual-screen systems get a “cocktail” layout. For single-screen systems, it displays two copies of screen 0, one rotated 180° for a pseudo-cocktail view; for dual-screen systems it displays screen 1 above screen 0, rotated 180° for a pseudo-cocktail view. How is that done? With a layout something like this:

<?xml version="1.0"?>
<mamelayout version="2">
    <view name="Cocktail">
        <screen index="0">
            <bounds left="-1.33333" top="0.0" right="0.0" bottom="1.0" />
        </screen>
        <screen index="0">
            <bounds left="0.01" top="0.0" right="1.34333" bottom="1.0" />
            <orientation rotate="180" />
        </screen>
    </view>
</mamelayout>

You”ll notice a couple of interesting things here. The first is that you can repeat the same screen multiple times in a view. For fun, you could even create a “quad” view that displays the screen four times rotated in all four directions. The second is that you can specify an orientation for screens and actually for any item. This allows rotation and flipping of items, and even works with vector monitors or other special cases. Finally, you see how the coordinate system really is arbitrary. Here we're using 1.333 as the width of each screen and 1.0 as the height. This is the essentially the same as 4:3.

The layout file format documentation is available on the MAMEdev documentation web site, and you can browse the internal layouts in MAME’s source code.