### FAQ - v0.38, 11-JAN-2013

### Questions

Build, installation and development issues:

Q1.1: QMC2 needs Qt 4.7+, but my (UNIX/Linux, Mac OS X) distribution comes with an older (or no) version of Qt. What should I do about that?

Q1.2: Aren't there any binary packages on the net?

Q1.3: I want to be at the cutting edge of QMC2 development. How do I access your development code base?

Q1.4: Why aren't you using autoconf/automake (configure)?

Q1.5: My (Linux) distribution already comes with a binary Qt 4 package, but the build fails. It complains about a wrong version of qmake or can't find it. What's wrong?

Q1.6: How do I know about the available make targets and build configuration options?

Q1.7: Build and installation instructions for specific distributions

Q1.7.1: Ubuntu 10.10, 11.04, 11.10, 12.04, 12.10 and 13.04 (including derived Ubuntu editions)

Q1.7.2: openSUSE 11.4, 12.1, 12.2, Factory and Tumbleweed

Q1.7.3: Fedora release 14, 15, 16, 17, 18 and 19

Q1.7.4: Mac OS X 10.6, 10.7 and 10.8

Q1.8: The build fails due to compiler errors regarding the accessibleName property used in emuopt.cpp

Q1.9: The standard icons of QMC2 are boring. Can I use alternate icon sets?

Q1.10: How do I create an alternate icon set for QMC2?

Q1.11: Why is feature/bug XYZ not yet implemented/fixed or completed? When will it be done?

Usage, tips & tricks:

Q2.1: When the game/machine list reloads, the insertion of games/machines is fairly slow. Is there a way to somehow speed it up?

Q2.2: How do I use the search feature?

Q2.3: What are the typical CPU & memory requirements?

Q2.4: What image or video formats are supported for in-game screenshots (previews), flyers, icons etc.?

Q2.5: What do I have to do to make QMC2 access my image & icon collections?

Q2.6: The menu fonts in MAME/MESS look ugly when started via QMC2. How do I fix that?

Q2.7: Nearly all MAME/MESS output is logged at once when the emulator finishes. What's up?

Q2.8: Sometimes when changing the global emulator options, QMC2 complains about an open game/machine-specific emulator configuration. What does this mean?

Q2.9: In rare cases, QMC2 hangs during emulation or after the emulator has finished. That's a bug, right?

Q2.10: I'm having trouble to set up the emulator configuration. Am I missing something?

Q2.11: What's required to make variant launching work?

Q2.12: The MAWS lookup feature is nice, but I would like to use a different catalog. Is it possible?

Q2.13: I want to use other/older emulators for specific games. Does QMC2 support that?

Q2.14: I'm primarily interested in the (SDL)MESS variant of QMC2. How do I setup any devices to be hooked up to the emulator?

Q2.15: There are just too many emulator configuration options, so it's hard to find the ones I want to set quickly. Is there an easy way to search for them?

Q2.16: Why does QMC2 differentiate between MAME & SDLMAME / MESS & SDLMESS? I thought they were the same thing, basically.

Q2.17: How do I backup / restore QMC2's configuration?

Miscellaneous FAQs, known bugs inside and outside of QMC2 etc.:

Q3.1: QMC2 doesn't determine the ROM state. What's wrong?

Q3.2: ROM state filtering takes veeeery long. What's up?

Q3.3: QMC2 crashes with a segmentation fault when I click the browse buttons of certain file settings (options dialog)

Q3.4: What does this QtWarningMsg: QPixmap::scaled: Pixmap is a null pixmap message in the front end log mean?

Q3.5: On PPC Linux all embedded images / icons are bluish

Q3.6: When KDE4's effects are enabled (compositing manager), QMC2 'flickers' when in full screen

### Answers

Q1.1: QMC2 needs Qt 4.7+, but my (UNIX/Linux, Mac OS X) distribution comes with an older (or no) version of Qt. What should I do about that?

First of all, don't worry. Regardless if an older version of Qt is already installed or not, you can use several versions in parallel. This includes self-compiled versions as in the following example. You only need to take care of the QMAKE make option as described in the build instructions of readme.html.

If you need to build Qt 4 from source, please follow these steps (on X11 platforms):

1) Download the latest source archive of Qt 4 from this URL: http://releases.qt-project.org/qt4/source/ -- for example http://releases.qt-project.org/qt4/source/qt-everywhere-opensource-src-4.8.4.tar.gz.

2) Extract this tar-ball to a directory where you are going to build it, then configure and build it completely:

    # mkdir -p src && cd src
    # gzcat /tmp/qt-everywhere-opensource-src-4.8.4.tar.gz | tar xfv -
    # cd qt-everywhere-opensource-src-4.8.4
    # ./configure -platform linux-g++ -fast -opensource -prefix /usr/local/lib/qt-4.8.4
    # make

Exchange the values for -platform and -prefix with things that fit your needs. The example is for a 32-bit Linux distribution, building Qt 4 on a 64-bit Linux system requires -platform linux-g++-64! See the available make specs in the Qt source (directory mkspecs/) for other platforms.

3) Install the library (it will be installed to the prefix-directory specified on the configure command line!):

    # make install

Now, following the instructions of readme.html, you should be able to build and use QMC2!!

This FAQ is somewhat obsolete: current versions of all relevant target OSs / platforms / distributions should include support for Qt 4.7 or above, or there's at least a binary SDK for it. More exotic environments may still need a local Qt installation, though.

Q1.2: Aren't there any binary packages on the net?

Yes. See http://qmc2.arcadehits.net/wordpress/download/#binaries for a list of known packages.

This list may not be complete, though. If you know of any binary packages that are missing, please contact us!

Q1.3: I want to be at the cutting edge of QMC2 development. How do I access your development code base?

We are using Subversion (SVN) for the code repository during development.

To checkout the latest revision of the source code, use the following command sequence (you have to checkout the code only once!):

    $ mkdir -p ~/src && cd ~/src
    $ svn co svn://svn.code.sf.net/p/qmc2/code/trunk qmc2
    $ cd qmc2 && make ...
    $ su
    Password:
    # make install

Later, if you need to update your local working copy, use the svn update command:

    $ cd ~/src/qmc2
    $ svn update
    $ make clean && make ...
    $ su
    Password:
    # make install

Please note that code from the SVN repository may be in an incomplete or even unstable state as it is code under development. We try to keep the SVN repository up to date with the latest intermediate MAME and MESS releases (a.k.a. u-releases), and since we're in direct contact with the MAME- & MESS-developers, we're also trying to keep up with all relevant 'latest developments'. So it can happen that a development revision of MAME/MESS is required in order to run QMC2's code from SVN!

To provide the community with good working combinations of QMC2 and MAME/MESS, we are striving hard to align QMC2 releases with stable MAME/MESS releases. Although we can't guarantee this in all cases, it's generally a nice approach for not-so-adventurous users and package maintainers. For quite some time now, we are releasing a new stable version each time a new stable MAME/MESS version gets released -- usually within hours or days!

Q1.4: Why aren't you using autoconf/automake (configure)?

Because QMC2 is a Qt based project. We use qmake instead, which fits better in this case and has equivalent functionality with regard to automatic platform configuration (and it's guaranteed to work everywhere where Qt can live).

Everything else -- that is, build or installation commands which are outside the scope of how we use qmake -- is under control of make rules and handled through architecture specific configuration files, which are stored in the arch/ directory.

See readme.html (multi-platform support) for more information!

Q1.5: My (Linux) distribution already comes with a binary Qt 4 package, but the build fails. It complains about a wrong version of qmake or can't find it. What's wrong?

The build configuration for your local setup is most likely wrong.

As discussed in readme.html (multi-platform support) you should either change the selected configuration (probably arch/Linux.cfg) to your local situation or make use of a distribution-specific configuration (if that exists).

To figure out what the right configuration file(name) for your OS & distribution is, run

    $ make os-detect

and note the configuration file(name) which is reported in the last line. Make sure it exists; if not, create this file (copy from another configuration or symbolically link to an existing one).

Now retry to build QMC2 with the use of the newly created distribution-specific configuration:

    $ make DISTCFG=1

If make is called this way, it will first try to load the global OS configuration settings from arch/`uname`.cfg (same as without DISTCFG=1) and then overwrite the settings with options specified in the distribution-specific configuration file (arch/`uname`/<distribution>.cfg). Obviously, you only need to overwrite those settings which are specific to your distribution and different from the global OS configuration.

Note that you have to specify DISTCFG=1 on every call to make if you need a distribution-specific setup, especially also for make install:

    # make install DISTCFG=1

If you want to know what settings will be used during the build, run

    $ make config [DISTCFG=1]

Also, make sure by means of your OS or distribution (rpm, yum, apt, rug, pkginfo, whatever...) that the installed Qt 4 version is really sufficient (see readme.html for software requirements).

Q1.6: How do I know about the available make targets and build configuration options?

From the base QMC2 source directory, run

    $ make help

to get a list of all available make targets and build configuration options (including their current values).

Q1.7: Build and installation instructions for specific distributions

This FAQ section lists the commands required to build QMC2 on several distributions which provide sufficient Qt 4 libraries themselves.

Although QMC2 will run out-of-the-box with the Qt libraries provided by these distributions, we always recommend to build Qt from source to circumvent potential issues of their Qt packages (see notes below, if applicable). In this case please follow the steps as described in readme.html which are basically the same for all platforms & distributions.

The distributions mentioned here are the ones we've successfully tested - QMC2 includes distribution specific build rules for all of them. To activate these rules, you'll have to specify DISTCFG=1 on every call to make (you can alternatively set this as an environment variable or edit the Makefile to change the default which is DISTCFG=0).

The following instructions generally work for code from the SVN repository as well as for stable QMC2 releases (which are distributed as source code tar-balls). The reason why the examples use SVN is simply that the code is more up to date :). Just leave out step 2 if you're going to use a released tar-ball instead (in this case you could also leave out the installation of the SVN client, of course).

The details...

Q1.7.1: Ubuntu 10.10, 11.04, 11.10, 12.04, 12.10 and 13.04 (including derived Ubuntu editions)

To build and install QMC2 from source (SVN) on

- Ubuntu 10.10 (Maverick Meerkat)
- Ubuntu 11.04 (Natty Narwhal)
- Ubuntu 11.10 (Oneiric Oncelot)
- Ubuntu 12.04 (Precise Pangolin)
- Ubuntu 12.10 (Quantal Quetzal)
- Ubuntu 13.04 (Raring Ringtail)

using their provided Qt packages, please follow these steps:

1) Install the required packages (including their dependencies)

    $ sudo apt-get install subversion g++ libqt4-dev libsdl-dev libphonon-dev libxmu-dev rsync

2) Either check out the source code from SVN

    $ mkdir ~/src; cd ~/src
    $ svn co svn://svn.code.sf.net/p/qmc2/code/trunk qmc2
    $ cd qmc2

or update the source code to the latest SVN revision

    $ cd ~/src/qmc2
    $ svn update

3) Build and install QMC2 with distribution-specific configuration turned on

    $ make DISTCFG=1 [EMU=<emulator>] && sudo make install DISTCFG=1 [EMU=<emulator>]

4) Clean up the source tree before building another variant

    $ make clean [EMU=<emulator>]

Q1.7.2: openSUSE 11.4, 12.1, 12.2, Factory and Tumbleweed

To build and install QMC2 from source (SVN) on openSUSE 11.4, 12.1, 12.2, Factory and Tumbleweed using their provided Qt packages, follow these steps:

1) Install the required packages (including their dependencies)

    $ su -
    Password:
    # zypper install subversion gcc make libqt4 libqt4-devel libqt4-x11 SDL-devel libkde4-devel rsync
    # logout

Note: the libkde4-devel package is only needed if you want to use the Phonon features (built-in audio player). If you don't want to use it, make sure to add PHONON=0 on the make command line in step 3) and all Phonon features will be cut off from the build!

2) Either check out the source code from SVN

    $ mkdir ~/src; cd ~/src
    $ svn co svn://svn.code.sf.net/p/qmc2/code/trunk qmc2
    $ cd qmc2

or update the source code to the latest SVN revision

    $ cd ~/src/qmc2
    $ svn update

3) Build and install QMC2 with distribution-specific configuration turned on

    $ make DISTCFG=1 [EMU=<emulator>]
    $ su
    Password:
    # make install DISTCFG=1 [EMU=<emulator>]
    # logout

4) Clean up the source tree before building another variant

    $ make clean [EMU=<emulator>]

Notes:

- Some KDE4 styles that come with openSUSE cause troubles such as single-click activation of games/machines. Select a different GUI style or change the style settings!

Q1.7.3: Fedora release 14, 15, 16, 17, 18 and 19

To build and install QMC2 from source (SVN) on Fedora release 14, 15, 16, 17, 18 and 19 using their provided Qt packages, follow these steps:

1) Install the required packages (including their dependencies)

    $ su -
    Password:
    # yum install subversion gcc-c++ qt4-devel qt-webkit-devel libXmu-devel SDL-devel phonon-devel rsync
    # logout

2) Either check out the source code from SVN

    $ mkdir ~/src; cd ~/src
    $ svn co svn://svn.code.sf.net/p/qmc2/code/trunk qmc2
    $ cd qmc2

or update the source code to the latest SVN revision

    $ cd ~/src/qmc2
    $ svn update

3) Build and install QMC2 with distribution-specific configuration turned on

    $ make DISTCFG=1 [EMU=<emulator>]
    $ su
    Password:
    # make install DISTCFG=1 [EMU=<emulator>]
    # logout

4) Clean up the source tree before building another variant

    $ make clean [EMU=<emulator>]

Q1.7.4: Mac OS X 10.6, 10.7 and 10.8

To build and install QMC2 from source (SVN) on Mac OS X 10.6 (Snow Leopard), 10.7 (Lion) and 10.8 (Mountain Lion) follow these steps:

1) Install the required packages / frameworks

- XCode: install Xcode from the Mac OS X install DVD and/or download/update it to the latest version -- note that we do no longer support building QMC2 through XCode itself (since this doesn't work in case of XCode 4.x), but command line tools (make, gcc/g++ etc.) and libraries that come with it are still required!
- SDL 1.2 framework: download and install the latest version of the SDL framework (http://www.libsdl.org/release/SDL-1.2.15.dmg)
- Qt 4.8 framework: download the latest Qt source code (http://releases.qt-project.org/qt4/source/qt-everywhere-opensource-src-4.8.4.tar.gz) and build/install your own self-compiled version of the Qt framework! You shouldn't use the official binary packages because 'qmake' then forces you to build your Qt apps through XCode again, which won't work (at least this was the case in Qt 4.8.0 - 4.8.2, so we decided to get rid of XCode in our build rules)!

2) Either check out the source code from SVN

    $ mkdir ~/src; cd ~/src
    $ svn co svn://svn.code.sf.net/p/qmc2/code/trunk qmc2
    $ cd qmc2

or update the source code to the latest SVN revision

    $ cd ~/src/qmc2
    $ svn update

3) Build and install QMC2 (the make rules will autodetect that this is Mac OS X)

    $ make [EMU=<emulator>] && sudo make install [EMU=<emulator>]

4) Clean up the source tree before building another variant

    $ sudo make clean [EMU=<emulator>]

Q1.8: The build fails due to compiler errors regarding the accessibleName property used in emuopt.cpp

If you see compiler errors similar to the following, please make sure that Qt Accessibilty has been enabled in your version / build of Qt!

    emuopt.cpp: In member function 'virtual QWidget* EmulatorOptionDelegate::createEditor(QWidget*, const QStyleOptionViewItem&, const QModelIndex&) const':
    emuopt.cpp:58: error: 'class QComboBox' has no member named 'setAccessibleName'
    emuopt.cpp:69: error: 'class QSpinBox' has no member named 'setAccessibleName'
    ...

Qt Accessibility is enabled by default and should really not harm in any way, but for strange and unknown reasons some binary Qt packages have it disabled. This has been seen on Gentoo, for example.

If this should be the case, please contact the package maintainer to change this and / or build Qt from source (recommended anyway :).

Q1.9: The standard icons of QMC2 are boring. Can I use alternate icon sets?

Yes. Since QMC2 v0.1.b11 there is support for alternate icon sets. You cannot switch them on-the-fly, though. QMC2 needs them built-in (most of them, only the ROM status icons are loaded dynamically).

Icon sets are stored below the data/img/ directory (data/img/<icon-set-directory>):

    $ cd ~/src/qmc2
    $ find data/img/ -maxdepth 1 -mindepth 1 -type d
    data/img/circles
    data/img/classic
    data/img/crazy
    data/img/crazy-black
    data/img/cubes

The classic icon set is the default.

To rebuild QMC2 with a different icon set, use the make command line option IMGSET as in the following example:

    $ make clean
    $ make IMGSET=crazy
    ...

Please don't forget to reinstall QMC2:

    $ su
    Password:
    # make install
    ...

Q1.10: How do I create an alternate icon set for QMC2?

Create a new directory below data/img/ for your icon set:

    $ cd ~/src/qmc2
    $ mkdir data/img/myIconSet

Create your icon images with any image creator / manipulator (i. e. The Gimp) and save them in PNG format. Make sure you use the exact same filenames as in the classic image set, and try to keep the icons the same size as their classic-pendants.

Images (from classic) you would like to reuse in your icon set don't need to be copied. Just create a symbolic link to its original:

    $ cd data/img/myIconSet
    $ ln -s ../classic/qt-logo.png qt-logo.png
    ...

If all went well, a simple rebuild of QMC2 with your image set as the value of the IMGSET parameter should do the trick:

    $ make clean
    $ make IMGSET=myIconSet
    ...

Don't forget to reinstall QMC2:

    $ su
    Password:
    # make install
    ...

Please send us your icon set so we can publish it with QMC2!

Q1.11: Why is feature/bug XYZ not yet implemented/fixed or completed? When will it be done?

It will be done when it will be done :)! Seriously, please never ask a question like this to developers of a free open source fun project driven by volunteers in their free time. Thanks.

Of course it's ok to request new features, ask for the planned timeline, report bugs (greatly appreciated!) etc., but whatever we might answer, it will always be just plans. We really care about what our users desire, but we can't promise anything, especially no finish dates. However, bugs will have the highest priority and -- if possible -- will be fixed ASAP.

Before you ask or report a bug, please always take a look at the current TODO list!

You may also consider to contribute or donate to the project, which both could help to speed things up :).

Q2.1: When the game/machine list reloads, the insertion of games/machines is fairly slow. Is there a way to somehow speed it up?

The short answer is yes :).

There are several ways to speed this up. The easiest and most efficient way is to hide the game/machine list while reload is active (simply click on the Search tab for example and you'll get a tremendous speed-up). It's probably best to display the hierarchical parent/clone view when loading the game/machine list. The item insertion to this view takes place at once after the full game/machine status has been determined; this is much faster than the online insertion into the master game/machine list.

The second thing to check is if you are sorting the game/machine list while reload is active (see Front end / Gamelist option Sort online); if so, disable it.

On the same configuration-page there is an option called 'responsiveness' which lets you decide after how many game/machine-insertions an update to the (master) game/machine list is made. Increasing this number may gain a slight speed up, but you will have to play with it because it directly interferes with the interactivity of the GUI - though only during game/machine list reloads. Setting this value higher than the total number of supported games/machines will gain the maximum possible performance and usually reduces the time for game/machine list processing to less than 2 seconds - at the expense of a more or less unresponsive GUI during reload, of course.

Since QMC2 v0.1.b11 the analysed data from a game/machine list reload is automagically cached and will be reused as long as the emulator version doesn't change. The result is a tremendous speed up for this process, which will be even greater if you set the responsiveness parameter a bit higher (250 - 500, for example).

Also note that complex GUI styles / style sheets can have some impact on performance -- as far as we've tested, the fastest styles (among the default set of styles) appear to be windows and plastique (without a style sheet).

As of version 0.2.b11, this FAQ is somewhat obsolete: per default QMC2 now hides the primary game/machine list when it's reloaded (during item insertion). Simply use the defaults and you should be set.

As of version 0.2.b14, this FAQ is even more obsolete:: the influence of the discussed 'responsiveness' parameter is no longer very remarkable! There have been some nice optimizations that should make it fast enough for everyone with just the defaults.

Q2.2: How do I use the search feature?

The game/machine search is a normal Qt based wildcard search that adds implicit globs (*) around each word which can be negated by using ^ for the start of a word or $ for using the end of the word.

For example, typing "s f z a j" results in "Street Fighter Zero 2 Alpha (Japan)". As you can see this allows you to navigate to specific games/machines with a minimum number of keystrokes. If you want to find the "CV version" of space invaders, all you have to type is "s i cv".

To negate the use of the implicit glob from the start of a word use ^, and to negate it from the end of a word use $. For example, "^a" will match all game/machine titles that include words starting with the letter A.

Other wildcard characters such as * and ? may also be used. * will match anything while ? matches any single character. For example, "ab*c" will match any game/machine title that contains AB followed by a C, whereas "ab?c" will match any game/machine title that has an AB followed by some character and then a C.

Be sure to spend some time experimenting with the search feature, you will find that with practice you can navigate to any game/machine you want with very few keystrokes.

Since v0.2.b20 the search string is now also matched against the game/machine-IDs (or short names). So in case of MESS, for example, entering a search string like "snes" would also return valid results.

Since v0.34 the same search method is used for software-lists.

Q2.3: What are the typical CPU & memory requirements?

Any modern x86 or x86_64 system should be okay for QMC2 and (SDL)MAME or (SDL)MESS. It may look different on other platforms, though. We've got positive reports for the ppc / ppc64 architecture as well (for example on a PS3).

Regarding memory requirements, a full-blown setup of QMC2 may use up to ~210 MB of memory in case of (SDL)MAME -- a bit less when certain features are disabled. When reloading the game/machine list, QMC2 additonally needs ~50 MB as a temporary buffer.

The numbers are much smaller in case of QMC2 for (SDL)MESS because there are much less machines to be managed (in contrast to several thousands in case of MAME); the typical memory consumption here is ~70 MB (+ ~5 MB as a temporary buffer).

Generally speaking, the amount of memory used by QMC2 mostly depends on these things:

- Number of games/machines the emulator supports
- Sizes of the image and icon caches
- Sizes of all loaded additional information sources such as the game/machine & emulator info DBs (optionally with in-memory compression)
- Qt version and feature set

So don't be surprised if it looks different for you!

When using the ROMAlyzer to analyze ROMs and CHDs of all games/machines, resident memory consumption can grow up to ~500 MB (MAME) / ~100 MB (MESS). However, with regard to the analysis of individual files, the ROMAlyzer will load only small chunks of data (up to 64 KB per chunk) to recalculate checksums -- this won't hurt.

All numbers were measured with QMC2 0.2.b15 and (SDL)MAME 0.137 / (SDL)MESS 0.137 (8604 games / 1260 machines, game/machine & emulator info DBs loaded with no in-memory compression, Phonon features enabled, many icons loaded).

Q2.4: What image or video formats are supported for in-game screenshots (previews), flyers, icons etc.?

Portable Network Graphics (PNG) is the primary image format supported by QMC2. In case of ZIP-archived icons (actually the only practical way to store them), ICO format is also supported since v0.34.

When loading images directly from the internet, QMC2 also supports other image formats such as JPEG. But when it's required to store them locally, they'll be converted to PNGs automatically.

Provided your Phonon back-end supports the video formats MP4 and FLV, QMC2 can also play YouTube videos (since v0.2.b20) which you can attach to each game/machine individually. Note that this may require additional codecs to be installed!

Q2.5: What do I have to do to make QMC2 access my image & icon collections?

QMC2 can handle images of in-game screenshots (previews), flyers, cabinets, control panels, marquees, title screens, PCBs, software snap-shots and icons stored in directories or ZIP archives.

Every image file (or ZIP member) must be named exactly as the corresponding lower-case game's/machine's short name, followed by the lower-case file extension ".png" (for example galaga.png or 1945kiii.png).

The use of ZIP archives requires a flat directory structure (= no sub-directories!). This is generally also true for image-directories, with the exception that for images stored in separate folders the direct use of screenshots created through MAME/MESS/UME is supported as well, so QMC2 also tries to find images in sub-directories which are named as <gamename>/XXXX.png / <machinename>/XXXX.png (XXXX = 0000 - 9999). The file with the highest number will be used, but only if <gamename>.png / <machinename>.png wasn't found in the base directory before.

Note also that you shouldn't overwrite the default snapshot naming scheme via the snapname option if you want QMC2 to find your previews on-the-fly. We currently only support the default naming of MAME/MESS (<gamename/machinename>/XXXX.png).

Make sure the access permissions to all image files and directories are setup correctly!

Software snap-shots need to be placed in a separate directory or ZIP-archive. Its sub-directory structure has to reflect the software list names for which the respective images are valid. For instance, software snap-shots for the gamegear software list have to be stored in a gamegear sub-directory, and image files in that sub-directory must be named exactly as their entry names in the software list, followed by ".png" (again, all in lower-case letters -- i. e. <software-snap-folder>/gamegear/aladdin.png). This applies to both the directory- and the ZIP-based storage of software snaps (in case of a ZIP archive <software-snap-folder> is omitted, of course).

See Front end -> Files / Directories in the setup dialog to modify the image paths, apply your changes and the images should be available to QMC2 right away (you'll have to clear the icon cache and trigger a reload of the game/machine list to also load the icons, though).

For best performance, we recommend to store icons in a ZIP-archive, and to store all other images directory based!

Icons are usually small, so reading one big file at once is much faster than reading many little files in a row. And in contrast to previews, flyers etc. which are loaded on demand (and stored in a least recently used pixmap-cache), icons are pre-loaded in one step, so it has major impact on the startup performance of QMC2 (when you're using icons). Also, when icons are read from a ZIP-file, QMC2 supports any image format that Qt supports and for which an image-format plugin is available (the magic is done by Qt). The raw image data is then made an icon and associated with the actual game/machine ID through the 'basenames' of the filenames as stored in the ZIP header. As a result, for instance MAMU's icons can be used out-of-the-box (ICO format)!

Q2.6: The menu fonts in MAME/MESS look ugly when started via QMC2. How do I fix that?

The most probable reason is you didn't setup the MAME/MESS option fontpath correctly! Change it to the directory where MAME/MESS has been installed and / or built (see Options -> Emulator -> Global configuration). The font files in question are ui.bdf and ui.bdc (will be created if it doesn't exist) and the default value of fontpath is "." (the current working directory), which is most likely not the correct path when MAME/MESS is started via QMC2.

Alternatively, you could of course also change the current working directory to the path where ui.bdf / ui.bdc reside before you start QMC2.

Since MAME/MESS 0.141 there's also an emulator option to specify a true-type font: see uifont!

Q2.7: Nearly all MAME/MESS output is logged at once when the emulator finishes. What's up?

This is caused by the way MAME and MESS buffer their output to the stdout stream. Unfortunately, there is no (standardized) way to solve this from within QMC2. We're aware that it works right when MAME or MESS are run in a shell, and so you might think that it's a bug of QMC2, but it isn't. The problem only occurs with piped output. Try "mame | less" for example - the behavior will be the same.

Since SDLMAME 0.130u2 this has been fixed (for SDLMAME and SDLMESS). A core fix is still missing, though.

Note that QMC2 will also work fine without this fix. It's more or less just a cosmetic issue... but from a front end's point of view, it's a bit more than that.

Q2.8: Sometimes when changing the global emulator options, QMC2 complains about an open game/machine-specific emulator configuration. What does this mean?

QMC2 uses two emulator configurations for each game/machine: the global setup and the game/machine-specific one. The global setup acts as a default configuration for all games/machines, whereas the game/machine-specific (or local) configuration may overwrite individual settings for the respective game/machine.

When you launch a game/machine or edit its configuration, QMC2 will process all settings in this hierarchical manner (global -> local) and thus open the configuration for the game/machine in question. It will be kept open until you select a different game/machine or change the game/machine-specific settings of another game/machine (which in this case will be opened instead of the previous game/machine).

Now, when you change the global emulator configuration while a game/machine-specific setup is currently open, you will have to decide what to do, because this will change the global defaults. QMC2 will ask you whether to keep the local setup as it is or to overwrite the local setup with the changed global defaults (or to revert the changes made - don't apply). If unsure, answer with overwrite, because this is probably what you are aiming to achieve :).

All emulator configurations - both global and local - will be saved in the user's QMC2 settings file (usually ~/.qmc2/qmc2.ini or ~/Library/Application Support/qmc2/qmc2.ini on Mac OS X) below the [emulator] section ([MAME] in case of MAME for example). See Configuration/Global/... for global settings and Configuration/<gamename>/... for game/machine-specific ones. Following the above guidelines of the hierarchical configuration scheme, only settings that are different than the respective default will be stored.

See also Q2.10.

Q2.9: In rare cases, QMC2 hangs during emulation or after the emulator has finished. That's a bug, right?

Yes and no - it's not a bug of QMC2 at least :). It can happen when you've limited the size of the emulator log and the emulator is excessively generating output to stdout or stderr. The function used to limit the log size is fairly slow in case of Qt 4.3, and so it may not be able to keep up with the speed of incoming messages. It's been observed for tinklpit (and SDLMAME 0.127) for example, which outputs a lot of subsequent popcount messages very quickly.

Qt 4.4.0+ doesn't appear to have this problem, so it's recommended to use Qt 4.4+ if you want to limit the in-memory sizes of the logs and not be affected by this issue.

This answer is obsolete: as of v0.35, Qt 4.7+ is required -- upgrade please!

Q2.10: I'm having trouble to set up the emulator configuration. Am I missing something?

You may be missing some background information about how QMC2 handles the emulator configuration internally. Let's try to fill that gap...

General configuration handling

When QMC2 launches an emulator, it will pass all the configuration parameters that are different than their respective defaults as command line arguments. There is no need for any external configuration files like ~/.mame/mame.ini (in case of MAME for example).

QMC2 uses a so called template configuration map (an XML template file loaded into a map of emulator options) to support all available settings it knows about. Options which are not included in the template will not be available via QMC2 (though it can be easily enhanced with additonal options). We are trying to keep up with the supported emulators and their latest versions; keep an eye on the template version reported in the front end log to make sure you're using an up to date configuration template. It uses the same versioning pattern as the emulator it supports.

If you would like to avoid any accidental mixture with external configuration files (mame.ini, mess.ini, gamename.ini, ...), you should set the value of readconfig to false (0). If this has been set, QMC2 will fully control the emulator configuration.

Using external configuration files

That said, it is still possible to use external configurations (and thus support unknown options out of the box). In fact, if you would like to use only external configuration files and not let QMC2 configure the emulators at all, just leave all emulator settings at their defaults within QMC2 (both the global and the game/machine-specific ones - see below). There's one exception, though: depending on your specific installation, you will most likely have to setup the (global) inipath parameter within QMC2 to make sure your ini's are found. Anyway, you will have to take care of these configuration files yourself, of course.

The value of readconfig (MAME and MESS) should be set to true (1) in this case, which is the default.

You can also mix both approaches, but note that the command line options (= settings made with QMC2) have higher precedence.

Importing and exporting emulator settings

Another option is to make use of QMC2's ability to import and export emulator configuration files. Exported configurations will contain all available (known) options, regardless if they are at their default values or not. Settings imported from configuration files will overwrite those currently set in QMC2 selectively (that is, only options that are included in the imported file will be changed).

Warning 1: The export function will blindly overwrite any existing configuration files - create backups if unsure.

Warning 2: The import function assumes a clean configuration syntax and may not be failsafe on malformed ini's. It's a fairly simple parser.

Warning 3: In contrast to the global emulator options, there is no ability to revert game/machine-specific settings (yet). As soon as the game/machine is started or a new game/machine is selected (and configured), the potentially wrong settings will be saved. So take care when importing game/machine-specific settings!

However, using this feature you are able to keep both worlds in sync and launch the emulators in the exact same way regardless if started via QMC2 or at the command line. It also provides an easy way to exchange game/machine settings between users and systems.

Global vs game/machine-specific settings

The global emulator options are used for all games/machines, which is obvious :). If a value is changed from its default (defined in the template) QMC2 will pass it to the emulator.

The same basically holds for any game/machine-specific options. The only difference is that if a setting has been made in the global configuration, this will be used as the new default.

For example, if you set flicker to 1.0 (default: 0.0) in the global settings, and to 2.0 in the game/machine-specific settings, -flicker 2.0 will be passed to the emulator. Any game/machine for which the flicker value hasn't been explicitly set will be called with -flicker 1.0.

How is the configuration stored?

All emulator settings are stored in QMC2's configuration file (usually ~/.qmc2/qmc2.ini or ~/Library/Application Support/qmc2/qmc2.ini on Mac OS X) - see the section for your emulator (for example the [MAME] section). Only options which were changed from their defaults get stored. QMC2 uses long option names which are compatible between command line and configuration files (i. e. scalemode and not sm).

You can pre-configure system-wide overwrites for any template-based defaults by storing them in /etc/qmc2/qmc2.ini on UNIX, or /Library/Application Support/qmc2/qmc2.ini on Mac OS X. System-wide pre-configuration is not supported (and not required) on Windows.

See also Q2.8.

Q2.11: What's required to make variant launching work?

UNIX (X11):

To be able to use the so called QMC2 variant launcher all QMC2-binaries (including the runonce utility!) must be installed in a place which is part of your search path -- make sure the environment variable PATH is setup correctly!

What the variant launcher effectively tries to do is run the following command:

    $ runonce qmc2-<variant> '<variant-title>' qmc2-<variant>

(<variant> = sdlmame, sdlmess, sdlume -- <variant-title> = M.A.M.E. Catalog / Launcher II, M.E.S.S. Catalog / Launcher II, U.M.E. Catalog / Launcher II)

As long as this doesn't work from a shell/terminal there's few hope it will work from QMC2 -- provided that in both situations the same PATH variable is used, of course.

We utilize the runonce utility in order to make sure that the called QMC2 variant will run only once (as the name suggests), and if it already runs, to raise its main window. Raising an application window from another program has some restrictions on X11, though. It's highly dependent on the window manager and its setup -- the window manager may simply ignore it completely, or it may interprete the event(s) in a different way.

On KDE for example, you'd have to use focus under mouse or focus strictly under mouse to make this work. Note that these settings may cause additional trouble in full screen mode if joystick support for the GUI has been enabled, because QMC2 may not lose its focus and would in turn react on joystick actions!

On Compiz Fusion, there's even more to do (quoting a post to the qmc2-devel mailing list):

It didn't work immediately, but I tracked that down to the fact that I was running Compiz Fusion as my window manager. I had to go into the CompizConfig Settings Manager, General Options, Focus & Raise Behaviour and remove the word "any" from the Focus Prevention Windows text box. This allowed the windows to bring each other to the front of the screen.

Note that enabling the GUI option Minimize on variant launch may help to circumvent most (if not all) of these possible troubles!

Any information on how to setup other window managers / desktop environments is greatly appreciated!

Mac OS X:

Variant launching on Mac OS X should work out-of-the-box without any modifications or additional setup as long as all QMC2 variants are properly installed to their usual places below /Applications/qmc2.

Windows:

As per default, variant launching on Windows assumes that all QMC2 variants can be found in the same directory, because that's how it's usually installed (and generally recommended). If you don't have any 'special' requirements, variant launching on Windows should pretty much work out-of-the-box.

However, we've added a Windows-only feature which allows you to specify the path to the other variant's exe file(s) explicitly if you would like to use separate installations or if you'd want to rename the exe files (for whatever weird reason).

You can additionally specify the command line arguments which are passed to the other variant's exe file when it's launched (also Windows-only). Note that this is an independent setting and will thus be used regardless if the other variant's exe file has been explicitly specified or not (leave empty for default behavior, which is to pass the same arguments that were used to launch the calling variant).

One important thing to note: Never use .bat or .cmd files to launch another QMC2 variant 'in your way'!

It won't work correctly because an already running process wouldn't be found since its exe name is not the same as the name of the .bat or .cmd file. So, instead of raising the running variant's main window another instance would be launched.

Q2.12: The MAWS lookup feature is nice, but I would like to use a different catalog. Is it possible?

Yes, within certain restrictions this is possible. All you need to do is change the MAWS base URL that QMC2 uses.

This can be accomplished through the detail setup dialog which you can open from the game/machine detail context menu (right-click on the tab header) or via the normal setup dialog which contains a button to open the detail setup (see front end's GUI tab). Select MAWS page (web lookup) in the list of available details and click on Configure.... Then, edit the base URL according to your needs.

The restrictions that apply are the following:

- The URL that you need to use for an individual game/machine must contain the game's/machine's ID (its short name). The placeholder '%1' will be replaced with the ID when retrieving the page, and it must be included in the URL pattern.
- The MAWS quick download links feature will only work for the original MAWS pages. Therefor, if you change the base URL to something different than the full-blown MAWS lookup, this feature will automatically be disabled.

A good alternative catalog based on the same data is mini MAWS for which the base URL would have to look like this (part of the suggested MAWS URLs):

    http://maws.mameworld.info/minimaws/romset/%1

The ArcadeHITS datObase may be used in this way:

    http://www.arcadehits.net/index.php?p=roms&jeu=%1

You can even use it to look up MAME Testers bug entries for the current set:

    http://mametesters.org/search.php?sticky_issues=off&sortby=last_updated&dir=DESC&hide_status_id=-2&custom_field_4=%1

To use the original (full-blown) MAWS catalog, the URL pattern should look like this (which is the default, and of course also part of the suggested MAWS URLs):

    http://maws.mameworld.info/maws/romset/%1

These are just some examples; there are a lot more on the net. However, even though this is quite flexible, not all available catalogs are working correctly with this feature. You've been warned :)! The ones mentioned above have been tested successfully, though.

Q2.13: I want to use other/older emulators for specific games. Does QMC2 support that?

Yes. Since version 0.2.b13 we support so called foreign emulators on a per game/machine basis. That is, we assume MAME-/MESS-like emulators which use the same game/machine IDs and ROM sets. It is mainly meant to drive older versions of MAME or MESS, specifically XMAME support has been revived through this new feature (though it's basically not limited to MAME or MESS variants).

Note, however, that QMC2's default emulator needs to be one of the officially supported set and that the configuration of foreign emulators is totally up to the user who needs to register each emulator with its (complete) command line options -- including a placeholder for the game/machine ID! If you omit the ID placeholder ($ID$) in the emulator registration, this mechanism will simply not work.

To add, copy or modify foreign emulators, go to the additional emulators tab in the emulator section of the global setup -- don't forget to apply/save the configuration changes when you're finished! Then select one of these registered emulators in any game-/machine-specific emulator configuration and you're done!

Officially tested (and in this context supported) foreign emulators include:

- XMAME 0.106
- RAINE 0.51.9

Note for X11 and Windows users: embedding of foreign emulators may only work correctly if they are close enough to current official versions of MAME or MESS (that is, SDLMAME / SDLMESS on X11-platforms or 'genuine' MAME / MESS on Windows)!

Q2.14: I'm primarily interested in the (SDL)MESS variant of QMC2. How do I setup any devices to be hooked up to the emulator?

Select the machine you want to emulate, then change to its Devices detail-tab (upper-right) and set up the devices like this:

1. Optional, but recommended: Click the Configuration button and select Default device directory for '<machine-name>'... so you can point QMC2 to a primary directory where you have your cart/rom/bin/whatever files for the current system. This directory will later be presented to you when you browse for device files. You only need to do this once, of course.
2. Click the only enabled button right to the device name (which says 'No devices' initially) to create a new empty device setup.
3. If you're going to use device files with speaking names, don't bother with setting up a name for the configuration... QMC2 will automatically do it for you!
4. From the (then enabled) list of available Device instances select the one (or more) you want to map a file to; when you click the browse button, the default directory from above will be used (if set), filtered by names that fit the contents of the Extensions column.
5. When you've selected the first file this way, QMC2 will suggest a configuration name (when the name hasn't been set before).
6. When you're done with the setup, click the save button (right-most tool button, now enabled as well).
7. The configuration will then be added to the list of Available device configurations and can be selected, edited and 'played' (launched).

Q2.15: There are just too many emulator configuration options, so it's hard to find the ones I want to set quickly. Is there an easy way to search for them?

Yes. Click into the tree widget which contains all the emulator configuration options and enter the string you want to search for. A small editor widget will pop up and all matches in the configuration tree will be high-lighted/expanded as you type. The widget closes when ESC is pressed or automatically after an idle time of 2 seconds.

This works for both the global and the game/machine-specific settings.

Q2.16: Why does QMC2 differentiate between MAME & SDLMAME / MESS & SDLMESS? I thought they were the same thing, basically.

Yes, since MAME/MESS 0.137 both SDLMAME and SDLMESS are included in the mainstream MAME and MESS source trees, so there's basically no longer a reason to distinguish between them.

However, QMC2 still needs this distinction because their configuration options are different in major parts (each supported target emulator has its own template), and there are also some minor differences with regard to the platforms involved (Windows vs. UNIX).

Q2.17: How do I backup / restore QMC2's configuration?

Backup:

1. Make sure that no instance of QMC2 is currently running.
2. Copy the configuration folder to a safe place.

Restore:

1. Make sure that no instance of QMC2 is currently running.
2. Overwrite the contents of the configuration folder with the contents of the backup.

There's really not more to it. Actually, it's even sufficient to just make a backup copy of the file qmc2.ini. Everything else will be recreated on demand (and should thus be removed from the configuration folder before QMC2 is restarted).

See also this section in the README in case you're unsure about the location of the configuration folder.

Q3.1: QMC2 doesn't determine the ROM state. What's wrong?

There are at least three possible scenarios:

1. Symptom: all games/machines are in an unknown state (blue)
   Probable reason a): You didn't trigger a ROM check.
   Solution: see Tools -> Check ROMs in the menu to trigger a ROM check.

2. Symptom: all games/machines are in an unknown state (blue)
   Probable reason b): The ROM state cache file cannot be read or written.
   Solution: see Tools -> Options -> Emulator -> Files / Directories -> ROM state cache and check your access permissions to that file.

3. Symptom: no games/machines were found (grey)
   Probable reason: The ROM path isn't set up correctly.
   Solution: Check the rompath-setting in your global emulator options (see Tools -> Options -> Emulator -> Global configuration)!
   Open the Search paths sub-tree and change the rompath setting according to your local setup.
   Apply your changes and retry the ROM check!

Please also check the front-end log for FATAL or WARNING messages!

Q3.2: ROM state filtering takes veeeery long. What's up?

You're most likely using Qt 4.3.2.

Qt 4.3.2 is known to have a bug which slows down the process of hiding items in a QTreeWidget (or QTreeView).

Use a different version of Qt! Qt Software promised to include the fix in Qt 4.3.3 and above (update: yes, the fix is included since!). A temporary fix for Qt 4.3.2 is available from the QMC2 home page (http://qmc2.arcadehits.net/wordpress)

This answer is obsolete: as of v0.35, Qt 4.7+ is required -- upgrade please!

Q3.3: QMC2 crashes with a segmentation fault when I click the browse buttons of certain file settings (options dialog)

You're most probably hitting a bug of Qt 4.3.x's QFileDialog class, which crashes when a hidden directory is passed to it (when a directory component of the file's path starts with a dot as in /home/user/.qmc2/qmc2.tmp).

As a workaround, you may either edit the file settings manually (and don't browse for these files) and / or change the corresponding directory names.

If you insist on using the file browsers, you'll have to wait for a fix for Qt 4.3.x which will hopefully be available soon.

The bug exists for at least these versions of Qt: 4.3.2 and 4.3.3 (not sure about 4.3.0 and 4.3.1, though). If you should be using a different version of Qt, please let us know!

Qt Software meanwhile confirmed the bug and fixed it for Qt 4.3.4!

This answer is obsolete: as of v0.35, Qt 4.7+ is required -- upgrade please!

Q3.4: What does this QtWarningMsg: QPixmap::scaled: Pixmap is a null pixmap message in the front end log mean?

This message means that the preview- or flyer-image which is about to be displayed is either not available or an invalid PNG.

If this message appears directly after the startup when no image is available for the restored game/machine selection (and the ghost image is displayed instead), it can safely be ignored! It's a known minor issue for versions <= 0.2.b2. If it appears at a later stage and you're sure the image exists and is a valid PNG, it may be a different bug :).

This answer is obsolete: as of v0.2.b3 the root cause of this issue has been fixed.

Q3.5: On PPC Linux all embedded images / icons are bluish

This was a known bug of Qt on that platform, prior to Qt 4.5.2.

This answer is obsolete: as of v0.35, Qt 4.7+ is required -- upgrade please!

Q3.6: When KDE4's effects are enabled (compositing manager), QMC2 'flickers' when in full screen

Change your kwinrc and disable UnredirectFullscreen:

    $ vi ~/.kde4/share/config/kwinrc
    ...
    [Compositing]
    UnredirectFullscreen=false
    ...

See also: http://staff.blog.ui.ac.id/jp/2009/06/10/flicker-on-compositing-enabled-kde4/