5. Video Mode Maker and Arcade OSD

5.2. Usage.

Video Mode Maker (VMM) and Arcade OSD (AOSD) have been conceived from a user-friendly perspective, in which there's no need for a deep knowledge about the technicalities involved in the display of a computer-generated picture. However, it is assumed that basic notions, particularly of the concept of video mode and CRTs classification, are already understood by the reader, so refer to the How a CRT works section for explanations on the subject in the case they're not.

We should remember that the point of this software is making modern video-rendering hardware for Windows-based PCs behave, display-wise, exactly like old dedicated video-rendering hardware did for proper usage of emulator programs, so the more the user's familiarity with the native video modes of the emulated systems is, the easier the usage of these tools becomes. For that purpose, we provide with lists of the different known video modes used by the most relevant video-game systems from the 80's and 90's in a dedicated chapter here, as well as independent chapters for their particular emulator programs.

5.2.2. Video Mode Maker: Generating video modes.

VMM is used to generate video mode lists in an automated way, for their use with CRT Emudriver. Although CRT Emudriver already installs a list of common video mode by default, you will probably want to customize it to better fit your particular monitor and set of emulators.

VMM is currently a console application, so it has no GUI. Using VMM is a simple task that consists on these steps:

1.- Do the configuration. This involves manually editing VMMaker.ini, ReslList.txt, and maybe MameMain.txt.

2.- Run VMMaker.exe (Run as administrator if you're in Windows 7).

3.- Reboot

Any further configuration can be done by repeating this process. Bear in mind that each time you run VMM, all existing modelines will be overwritten. Take care of this in case you had done manual adjustments to the current modelines.

VMM uses two sources of information as input for the list of video modes it will calculate:

- XML List: this is used specifically for the MAME/MESS/UME emulators. These can output all the native video modes for their emulated systems in .xml format. VMM can then use this information to automatically create the required video modes.

- Custom List (ReslList.txt): this is a list in plain text format which the user can freely customize, by adding or removing video modes that will be later created by VMM. Just be careful to follow the format and spacing.

Both sources can be used simultaneously, and an independent set of options applies to each of them (see below suffixes "_XML", "_custom"), so you can filter and rationalize the resulting list to your convenience.

VMM assigns the highest priority to the video modes from the Custom List, and relegates the ones coming from the XML list to lower priority. You can still promote one video mode from the XML list to high priority by adding its source game name to the MameMain.txt list. Priorities are important because usually VMM will need to prune the resulting modelist in order to get it to fit in the driver's memory. In this situation, low priority modes are dropped first.

Now we will discuss the different options in VMMaker.ini. You have samples for typical use cases in the Apendix B of this chapter. VMMaker.ini is divided itself into four main sections, and should be edited as follows:

1) MAME

- MameExe: use this option to enter the full path of your MAME/MESS/UME executable file. E.g.: MameExe =  "c:\Emu\MAME\mame.exe". If you'd like to get video mode information simultaneously from MAME and MESS, use one of the existing combined builds (UME). This option is only required if GenerateXML is enabled.

- IniPath: use this option to enter de full path of your MAME .ini folder. E.g: IniPath = "c:\Emu\MAME\ini\". Mind the ending backslash! This option is only required if GenerateInis is enabled.

- ListFromXML: Use this option to enable video information being listed from an XML source. The information is extracted from the emulator program itself, which stores all the modelines used by the games it emulates in an .XML file. For this, you need a version of MAME/MESS/UME previously installed. Keep in mind that these video modes have been defined by the emulator's coders themselves, and could not be totally accurate depending on the emulation status for every particular game/system. For arcade games in general, there isn't currently a better video documentation source than MAME, anyway.

- GenerateXML: Enable this option to actually retrieve the XML file from MAME/MESS/UME. Because this is a slow process, it is generally fine to do it just once, and then disable this option so the next time you run VMM it can reuse the already generated XML file.

- OnlyListMain: By using this option, you can force VMM to only create the video modes from the games contained in MameMain.txt, when the XML file is processed. All other modes from the XML file will be discarded. This is useful in case you're only interested in emulating a few games.

- GenerateInis: enable this option if you want VMM to automatically configure MAME in a per-game basis -- it can create the .ini files the emulator uses for every game, so that you don't have to set every particular game's video options for the native video modes. This option is meant for official MAME. The use of individual .ini files has become obsolete since the development of GroovyMAME.

- MonitorHorizontal: enable this option if you want vertical games to be rotated so that you can run them on a horizontal monitor. Instead of their native resolution, a suitable rotated video mode will be calculated. Horizontal games will keep their native resolution. If this option is disabled, both horizontal and vertical games will keep their native resolution, meaning that you will need to physically rotate your monitor in order to display the vertical ones.

- RotatingDesktop: enable this option if you're planning to rotate Windows' desktop as well when you physically rotate your monitor. This option only affects the options applied to .ini files, in case these are created.

- VerticalAspect: by default, VMM will calculate the resolution of rotated vertical games so that it matches the correct aspect ratio, usually 4:3 (3:4 when rotated). Some users find the correct aspect too "skinny" and prefer a wider picture. This option allows enforcing any aspect ratio for rotated vertical games:

   4:3 (keeps original aspect ratio)
   3:3 (stretches to square format)
   3:4 (stretches to full screen)
   h:v (custom aspect ratio)

2) MONITOR

-MonitorType: Use this option to define the type of monitor in use (since CRT Emudriver is able to work with any type of monitor and not just 15-kHz ones), so that VMM generates the modelines properly for your monitor's specifications. The following presets are included in VMM:

- MonitorType = "GENERIC" Standard 15-kHz monitor (15.7 kHz)
- MonitorType = "NTSC"      Standard 15-kHz-only NTSC CRT TVs
- MonitorType = "PAL"        Standard 15-kHz-only PAL CRT TVs
- MonitorType = "CGA"       Standard resolution "CGA" monitor (15.2-15.7 kHz)
- MonitorType = "EGA"       Medium resolution "EGA" monitor (24.9 kHz)
- MonitorType = "VGA"       High resolution "VGA" monitor (31.5 kHz)
- MonitorType = "MULTI"    Multi-sync CRT PC monitors (54-82 kHz)
- MonitorType = "D9800"    Wells Gardner D9800, D9400 (15-38 kHz)
- MonitorType = "D9200"    Wells Gardner D9200 (15-38 kHz)
- MonitorType = "H9110"    Hantarex MTC 9110 (15.6-16.7 kHz)

By default, MonitorType is set as "CUSTOM", and a sample monitor_specs line is provided, which should be good enough for the average 15 kHz arcade monitor and CRT TV. Notice that most CRT TVs are actually multi-standard. This means that they will support both PAL and NTSC signals. In this case you'd better leave the default configuration, instead of choosing any of the "PAL" or "NTSC" presets, which are only meant for TVs that require strictly standarized timings.

- monitor_specs_0-9: A more technical approach involves keeping the MonitorType line as "CUSTOM" and manually defining the monitor's specifications by editing the line monitor_specs_0. Though this is the way to get the best performance out of your particular monitor through CRT Emudriver, it requires proper technical knowledge of your monitor and a deeper understanding of how a CRT works, so it's aimed only at advanced users, therefore we'll explain the method in a separate subchapter here. Keep in mind, nevertheless, that this method will serve to also solve generalized problems regarding screen geometry and visible area which may appear after generating video modes with any of the monitor presets.

3) MODELINE GENERATOR

- TotalModes: This option defines to maximum number of video modes to be generated. By default it is set to 120, which is a safe value for all CRT Emudriver versions. Only the version based on Catalyst 6.5/32-bit allows up to 200 modes. Remind that Hyperspin frontend will fail to start if too many video modes are defined.

If processing both the XML and Custom Lists results in the TotalModes value being exceeded, VMM will need to prune the mode list, until it meets the TotalModes value. Discarded video modes are listed in the Droplist.txt output file after the process. The pruning process intends to be intelligent. Modes that are used by few games or are easily substituted for another one in the list with minor issues are dropped first. As explained above, modes from the Custom list have the highest priorty and should be dropped in the last place, as well as the ones belonging to games from MameMain.txt.

Being able to deal with huge mode lists has been crucial in the past. However, since the development of GroovyMAME, this is not a critical factor anymore.

The following group is presented as pairs of options, with the suffixes "_XML" and "_Custom". What you need to understand is that the "_XML"-ending options apply to the video modes from the XML List, while the "_custom"-ending options apply to the ones from the Custom List. This is very important because it allows using different criteria depending on the source.

- ModeTableMethod_XML / ModeTableMethod_Custom: these options define the method you want to use when creating the mode table. The values allowed here are the following:

    0 = Static Table: video modes are generated keeping their original vertical refresh rate. This is the method you will usually apply to the modes from the Custom List and also to the XML List in case you use official MAME and .ini files per game.

    1 = Dynamic Table: a table of dummy modes is created using the width and height native values while ignoring the vertical refresh. This method is intended to be applied to the XML List to create a suitable mode table for GroovyMAME. No .ini files are requiered in this case (remind to disable the CreateInis option.

    2 = Magic Table: a table of "magic" resolutions is created, in the form 1234 x height, by ignoring the native width and refresh and only keeping the height. This method drastically reduces the size of the mode list. It's only supported by GroovyMAME under Windows XP (it won't work under Windows 7), and is intended as a workaround for the Hyperspin issue.

When using the Static Table method, care must be taken if you're defining two instances of a given resolution with different but close refresh rates (closer than 1 Hz). You may run into an issue because the operating system labels the refresh rate with an integer number. For this reason both modeline definitions will overlap. The traditional workaround has been incrementing the logical width of the video mode by one pixel for each refresh variant, and matching each game with the proper variant in its .ini file. VMM does this automatically for you automatically in order to avoid overlapping labels. Unfortunately this workaround no longer works in Windows 7, making the Static Table method mostly unusable for XML sources in practical cases. In this situation, the use of GroovyMAME combined with a Dynamic Table is the only reasonable approach. However, you will still need the Static Table method to deal with the video modes required by other emulators that don't manage refresh rates by themselves like GroovyMAME does. In these cases, you will need to define the video modes with their exact refresh rates in ReslList.txt, paying attention not to generate cases where the refresh rates would overlap as described above.

When using the Magic Table, GroovyMAME overwrites the dummy "1234" value with the native width of the emulated game, creating a genuine modeline with the required width. This is actually a hack and may work great in many systems while causing issues in a few. It is strongly recommended to use Direct3D instead of DirectDraw when using this method.

As an alternative to the Magic Table that is compatible with both Windows XP and 7, you can use "super" resolutions. This is a special case of Dynamic Table, where the native width is substituted by a super-wide resolution, usually 2560, meant to perform fractional stretching over the horizontal axis, while keeping the native height unmodified. Due to the nature of CRT monitors, provided a high enough horizontal resolution is used this method produces no visual artifacts. A special "ReslList - super.txt" file is provided with instructions to set up "super" resolutions. This method is becoming the rule in the emulation scene, driving the other ones into obsolescence.

- XresMin_XML / XresMin_Custom: This option simply sets a minimum value for the horizontal resolution. Lower values will be replaced by this one.

- YresMin_XML / YresMin_Custom: Idem but for the vertical resolution. This option is important in order to optimize your mode table. With standard arcade monitors and from a hardware point of view, vertical resolutions below 240 lines are totally equivalent to displaying the same resolution within a 240 line mode and adding black borders as padding above and below the active lines. For this reason, creating those resolutions is redundant and a waste of space in the mode list, so it is recommended to set this value to 240. However this is only true if you use an emulator that is smart enough to center the vertical resolution without stretching it (GroovyMAME is, and official MAME too when used with DirectDraw).

- YresRound_XML / YresRound_Custom: Use this option to optimize the resulting mode list. By rounding the height to the next defined multiple VMM will produce a more reasonable mode list, while keeping the visual features intact. These are the allowed values:

    0 = Leave original value
    1 = Round to next 2-multiple
    2 = Round to next 4-multiple
    3 = Round to next 8-multiple
    4 = Round to next 16-multiple

Bear in mind that some of the values above can prevent common resolutions from being created. E.g. 800x600, when using 16-multiples won't be created as such, because 600 is not divisible by 16.

- DotClockMin: Use this option if your video card can't support low dotclocks. As a workaround, VMM will duplicate the horizontal resolution of the video mode, whenever the calculated modeline results in a dotclock under the value specified by this option. To make use of this you will need an emulator that is capable of integer scaling on the horizontal axis (any MAME build is). The value must be specified in MHz. E.g. DotClockMin = 7.010

- Iterations: This option allows increasing the accuracy of the resulting refresh by successive iterations of the modeline generator. Valid values are 0-5. To use this option, a valid look-up table of precalculated dotclocks is required. One sample of this table is provided for the Radeon 9250. Users of this card can benefit from the extra accuracy when using this option. For other cards, this option won't result in any improvement, so it's better to keep it disabled.
 

4) DRIVER

- DisplayName:  This option allows VMM to point to the right device when creating modelines. Usually it will be "\\.\DISPLAY1", unless your system has more than one video card. If that is the case you will need to find out the display number that represents your target Radeon card and edit this option accordingly.

- DriverPath: This option sets the path to the driver installation files (".\Driver\" by default), in order to add the modeline definitions directly into the driver's .inf files, making it useful for cloning the current setup on further driver installations. Starting from Windows 7, digital signature is required for .inf files, making this feature obsolete.

UpdateDriver: This option is used in combination with DriverPath in order actually enable the driver's files update, as explained above. Same remarks apply.

- UpdateRegistry: By enabling this option you allow VMM to install the calculated modelines in the Windows registry. Default value is enabled. You can disable this option if you want to use VMM as a simple modeline calculator, without modifying your current setup.

- AnyCatalyst: By enabling this option you can force VMM to install the calculated modelines even with regular Catalyst drivers (non-CRT Emudriver).

The ReslList.txt file format consists in a simple list of video modes, in the form "width x height @ refresh label". You must respect the proper spacing just as shown below, otherwise the file parsing will fail:

## Samples ##

 640 x 480 @ 30.000000 desktop1
1280 x1024 @ 60.000000 desktop2
 256 x 224 @ 60.098475 superfam

Finally, you may want to edit the MameMain.txt file. VMM makes a selection among the whole XML source attending firstly to the games/drivers defined in the MameMain.txt file, which will get priority only after the modes defined in ReslList.txt.

MameMain.txt can be edited according to the user's preferences, so you can delete or add the games/drivers corresponding to the video modes you want by following the format (it uses MAME's romset/driver names), once you know them by way of MAME documentation. You can also use MameMain.txt in combination with the OnlyListMain option explained above, to filter out anything that's not in this list.

The entries in MameMain.txt as default have been chosen so that any relevant title gets it's video mode created, but the list is always susceptible of being modified. A sample of the expected format is shown below:

brkthru,   "Kyohkoh-Toppa"
ninjakd2,  "UPL"
mustang,   "NMK 1989"
snowbros,  "Snow Bros"
bublbobl,  "Bubble Bobble"

Appendix A: Defining monitor specifications.

Introduction

You need to be aware that there is a real risk of damaging your monitor if the wrong settings are used here, so it is not a good idea to mess with this unless you really understand what you are doing. However, this is probably the only way to use your monitor to its full potential.

You can generate video modes for nearly any imaginable monitor specification by means of the use of monitor_specs lines. Each of these lines defines a safe range for horizontal and vertical frequencies which your monitor can work with. Usually you will only need to define one single monitor_specs line to fully configure a standard CRT monitor or TV, but multi-sync monitors are modelized by using more than one monitor_specs lines, each one representing one of the monitor's work ranges, so a typical 15/24/31 KHz multi-sync monitor would require three monitor_specs lines, numbered consecutively as monitor_specs_0, monitor_specs_1, monitor_specs_2.

The aim of the monitor_specs line is to provide an exact description of the video signal timing to be generated for a specified frequency range as required by your monitor, as well as a couple of parameters adjustable to the user's preference, which control how the modeline generator deals with video modes that fall outside the boundaries of the defined ranges.

You must not mistake monitor_specs with modelines. In a way, monitor_specs can be seen as a template to calculate modelines from. So modifying parameters in monitor_specs will automatically propagate the changes to any modeline calculated after that, making this a very powerful system for controlling video geometry.

Format of monitor_specs lines

monitor_specs_{0-6} = "HfreqMin-HfreqMax, VfreqMin-VfreqMax, HFrontPorch, HSyncPulse, HBackPorch, VfrontPorch, VSyncPulse, VBackPorch, HSyncPol, VSyncPol, ActiveLinesLimit, VirtualLinesLimit"

- Subindex: 0 to 6, makes possible defining more than one monitor_specs line. The first subindex should always be 0.

- Frequency ranges: Define the ranges of both horizontal and vertical frequencies that the monitor is capable to work at. At the same time, it specifies the ranges of frequencies where the rest of parameters in each monitor_specs line will be applied.

  HfreqMin-HfreqMax: Minimum and maximum horizontal frequency, in Hz
  VfreqMin-VfreqMax: Minimum and maximum vertical frequency, in Hz

- Horizontal timing settings: Define the duration of each of the horizontal blanking interval elements. Values in microseconds (µs). All values must be greater than zero. Refer to your monitor's manual for the minimum required values.

  HFrontPorch: Horizontal front porch period.
  HSyncPulse: Horizontal sync pulse period
  HBackPorch: Horizontal back porch period

  Use this settings to adjust horizontal geometry (amplitude and centering).

- Vertical timing settings: Define the duration of each of the vertical blanking interval elements. Values in miliseconds (ms). All values must be greater than zero. Refer to your monitor's manual for the minimum required values.

  VFrontPorch: Vertical front porch period.
  VSyncPulse: Vertical sync pulse period.
  VBackPorch: Vertical back porch period.

  Contrary to the horizontal case, vertical amplitude is usually not adjustable by tweaking these settings, only centering is possible in most cases.

- Sync polarities:
  HSyncPol,VSyncPol: polarities, not in use! defaults to negative.

- Line limiters:
  ActiveLinesLimit: Vertical resolutions until ActiveLinesLimit value included, are generated as progressive, regardless the possibility of obtaining the required vertical refresh value.

  VirtualLinesLimit: Vertical resolutions above ActiveLinesLimit and below VirtualLinesLimit are virtualized, that is, an interlaced resolution bigger that the native one is generated, with the right refresh, and "hardware stretch" is applied. Vertical resolutions above VirtulaLinesLimit are generated as interlaced, without any stretching.

Modelizing your monitor by using monitor_specs lines

Basically, monitor_specs lines are used to divide your monitor's operational range in bands where different settings are applied, which will determine the right picture geometry within that frequency range. All video modes that fall inside a defined band will be calculated using the same timing values, thus minimizing geometry differences between video modes.

Monitors which can work at two or more horizontal frequencies are usually referred as multi-sync. Strictly speaking, this actually means that the monitor can synchronize within two or more frequency ranges. If these ranges are relatively narrow and separated among them, we say the monitor has a 'banded' design.

For instance, a 15.75 / 24.60 KHz dual sync monitor will probably work fine within a first range of [15.45 - 16.05] KHz and a second range of [24.30, 24.90] KHz, being those intervals built, in this particular sample, by considering a ±0.3 KHz tolerance around both nominal values (the appropiate tolerance ranges are the ones specified by the manufacturer). So, this dual sync monitor would require two monitor_specs lines to be defined:

Frequencies not included within these ranges, such as 18.00 KHz or 31.50 KHz, will not be created by using these settings. This minimizes the risk of producing out of range frequencies.

Some new multi-sync arcade monitors can actually work at any horizontal frequency inside a continuous range from 15 KHz up to 31 or even 38 KHz. Despite of that, you can't use the same timings through the whole range. The reason is that low resolution video standards such as CGA use much longer line, porch and sync times than higher resolution standards as EGA or VGA, so a monitor designed to deal with different standards needs to readjust itself depending on the input signal. However, there is not a smooth transition from CGA to EGA or EGA to VGA as one could expect, rather than that there's a critic point somewhere in the middle of both standards from which the monitor will decide to jump to the upper one.

However, truly multi-sync monitors should be capable of synchronizing to any arbitrary horizontal frequency, provided it falls within a continuous range defined by a minimum and a maximum value, such as [31.00 - 50.00] KHz. PC monitors usually belong to this group. There is an industry standard for these monitors known as VESA GTF (Generalized Timing Formula) that defines the exact timing of a video signal at a specific frequency. VESA compliant monitors can accept any signal calculated by the GTF algorithm and automatically center the picture as the size of the borders is a known variable.

GTF is based on stablishing standard proportions between active video and blanking relative duration. On the other hand, monitor_specs lines use absolute values to define blanking times. Thus, you can't modelize GTF by means of monitor_specs lines, unless you used a lot of small discrete intervals. Despite of that, PC monitors are usually flexible enough to accept a single specification for the whole range. Of course, there will be geometry variations between different video modes, but you can use your monitor's OSD to create and save individual adjustments for each of them.

Some CRT TVs which are designed to accept multi-standard (PAL/NTSC) RGB signals via SCART, can't properly deal with all the continuous range of frequencies that spans from PAL frequencies (≈50 Hz) to NTSC frequencies (≈60 Hz). This is the case of many newer sets that mount a digital chasis.

These sets will happily admit frequencies that are close enough to those standards, and will usually apply some geometry correction adjustments that are specific for the standard they think they are dealing with. On the other hand, frequencies that are somewhat in the middle, like 55 or 57 Hz, will cause all sort of unpredictable behaviours, tipically distorted geometry or just an out of sync display. In this respect, these sets can be treated as banded multi-sync monitors, with two ranges around 50 Hz and 60 Hz respectively, separated by a gap, which width needs to be determined through experimentation. Unfortunately, this gap will for sure include frequencies that are fundamental ones in the arcade realm, making these TV sets unsuitable for fully accurate emulation. However, a compromise setup may usually be possible, by defining two monitor_specs lines.

Using these settings, all video modes above 248 lines will be calculated using the first line (monitor_specs0), thus limiting the vertical refresh value to a maximum of 52.40 Hz. On the other hand, video modes below or equal to 248 lines will be calculated with either interval which defined vertical refresh boundaries result closer to the desired refresh.

Finally, monitor_specs lines don't need to represent a physical monitor at all. Instead of that, you can use monitor_specs lines just to define some ranges you want your modelines to be produced. An usual case would be to define a range for standard CGA low resolutions, and a second range for VGA high resolutions. Each of these ranges would be targeted to different physical monitors, though it's perfectly possible to have the resulting video modes simultaneously present in the system, ready to be used when required, or just calculate them for later use. Of course, if this is the case, it's the user's responsibility to direct each video mode to the right monitor.

In the sample above, the idea is to produce CGA video modes with the first line, and VGA ones with the second.

Modeline scoring

For the previous explanation, we have assumed that when multiple monitor_specs lines are defined, only one of them (the most suitable one) will be used to produce the final output modeline for each situation, depending on the target video mode specs.

Although this is totally true from the user's point of view, it's important to explain how the modeline generator ends up deciding which range to use for a particular video mode, as only a deep understanding of how this mechanism works will allow us to create our own monitor_specs definitions with predictable results.

The basic idea here is that when we request a particular video mode, a viable modeline will be produced for each of the ranges defined. For instance, if we have created three monitor_specs lines, three modelines will be calculated (one for each resulting range). Obviously, producing a viable modeline using unsuitable ranges will require a substantial modification of the original video mode, in order to keep the frecuencies inside the defined ranges. This is achieved by different methods, such as line padding, line doubling, frequency lowering, frequency doubling, etc. including the extreme case where total virtualization of the video mode is required. Each of these modifications introduces an amount of degradation, that the modeline generator uses to compute the modeline score, a value that reflects the degree of degradation of a given modeline. So once the modeline generator has calculated a viable modeline for each of the ranges, it will pick the one with the best score, which should correspond with the most suitable range for the target video mode.