### FAQ - v0.2.b8, 23-APR-2009

### Questions

Build, installation and development issues:

Q1.1: QMC2 needs Qt 4.4+, but my (Linux) distribution comes with an older 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 8.04 and 8.10 (including derived Ubuntu editions)

Q1.7.2: openSUSE 11.0 and 11.1

Q1.7.3: Fedora release 9 and 10

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?

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 formats are supported for in-game screenshots (previews), flyers & icons?

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: When I try to launch another QMC2 variant from a currently running one, nothing happens. What's up?

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

### Answers

Q1.1: QMC2 needs Qt 4.4+, but my (Linux) distribution comes with an older 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 some environment variables 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://www.qtsoftware.com/downloads -- for example qt-x11-opensource-src-4.5.0.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-x11-opensource-src-4.5.0.tar.gz | tar xfv -
    # cd qt-x11-opensource-src-4.5.0
    # ./configure -platform linux-g++ -prefix /usr/local/lib/qt-4.5.0
    # 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

This is VERY important for Qt 4 (whereas in case of Qt 3 this wasn't necessary)!

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

Note that building Qt from source is recommended for QMC2, even if your distribution already comes with sufficient Qt 4 packages. Some distributions use buggy versions of Qt (performance issues, potential crashes), others do not include all the required features. Installing Qt as described here is guaranteed to work with QMC2 - provided that Qt itself builds cleanly :). On Linux at least, there should be no problem at all to build Qt from source. On most other platforms supported by Qt this is true as well.

See here for official installation instructions (covering all platforms): http://doc.qtsoftware.com/4.5/installation.html

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

Please see http://qmc2.arcadehits.net/download.html for more information.

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 https://qmc2.svn.sourceforge.net/svnroot/qmc2 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. At some point in time - when several new features were incorporated and the code base stabalizes again - we decide to pick a specific SVN revision and publish it as the final release of a respective version. File releases should be more or less working fine and can be considered as stable, which does not necessarily mean that they are bug-free :).

To always 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.

Because QMC2's roots are MAME based, we've decided to release a new stable version every time a new stable SDLMAME version gets released. The stable SDLMESS release usually follows within hours or days. As soon as that's available, we check the compatibility and post a patch for the SDLMESS variant of QMC2 if required.

We try to keep the SVN repository up to date with the latest intermediate SDLMAME release.

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.

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). You'll need the Qt 4 core libraries and the development packages.

Here's an example for an RPM-based distribution (openSUSE 11.0):

    # rpm -qa | grep libqt4
    libqt4-devel-doc-4.4.0-12.3
    libqt4-x11-4.4.0-12.4
    libqt4-qt3support-4.4.0-12.4
    libqt4-sql-sqlite-4.4.0-12.4
    libqt4-devel-doc-data-4.4.0-12.1
    libqt4-4.4.0-12.4
    libqt4-devel-4.4.0-12.4
    libqt4-sql-4.4.0-12.4

Underlined packages are required for QMC2 to build and run. The library versions may differ, though (Qt 4.4+ required).

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

Run

    $ make help

for more information.

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 8.04 and 8.10 (including derived Ubuntu editions)

To build and install QMC2 from source (SVN) on

- Ubuntu 8.04 (Hardy Heron, Debian lenny/sid)
- Ubuntu 8.10 (Intrepid, Debian lenny/sid)

using their provided Qt 4.4 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 rsync

2) Either check out the source code from SVN

    $ mkdir ~/src; cd ~/src
    $ svn co https://qmc2.svn.sourceforge.net/svnroot/qmc2 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
    $ sudo make install DISTCFG=1

On Hardy Heron, you may have to use

    $ make DISTCFG=1 PHONON=0
    $ sudo make install DISTCFG=1 PHONON=0

instead, which disables the Phonon features.

Q1.7.2: openSUSE 11.0 and 11.1

To build and install QMC2 from source (SVN) on openSUSE 11.0 or 11.1 using their provided Qt 4.4 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 https://qmc2.svn.sourceforge.net/svnroot/qmc2 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
    $ su
    Password:
    # make install DISTCFG=1
    # logout

Notes:

- The Oxygen default style from KDE 4 causes some troubles such as single-click activation of games/machines and strange Qt warnings. Select a different GUI style to fix that.

Q1.7.3: Fedora release 9 and 10

To build and install QMC2 from source (SVN) on Fedora release 9 and 10 using their provided Qt 4.4 packages, follow these steps:

1) Install the required packages (including their dependencies)

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

2) Either check out the source code from SVN

    $ mkdir ~/src; cd ~/src
    $ svn co https://qmc2.svn.sourceforge.net/svnroot/qmc2 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
    $ su
    Password:
    # make install DISTCFG=1
    # logout

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/classic
    data/img/crazy-black
    data/img/crazy

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!

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 remarkable 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 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.

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 games/machines that start 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 that has an AB followed by a C, whereas "ab?c" will match any game/machine 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.

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

Any modern x86 or x86_64 system should be okay for QMC2 and SDLMAME or SDLMESS. 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, QMC2 typically uses ~160 MB sustained resident memory in case of SDLMAME (a bit less when Phonon 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 SDLMESS because there are just several hundred machines to be managed (in contrast to several thousands in case of MAME); the typical memory consumption here is ~40 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)

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 ~480 MB (MAME) / ~55 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.b7 and SDLMAME 0.129u4 / SDLMESS 0.129 (7800 games / 738 machines, game/machine & emulator info DBs loaded with in-memory compression, Phonon features enabled).

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

Portable Network Graphics (PNG) is the only image format supported by QMC2!

This is true for icons as well which are usually in ICO format - you'll need to convert them to PNGs before they can be used with QMC2.

We plan to also support preview movies in the future. These will have to be in formats supported by Phonon and its backend API such as gstreamer; existing codec plugins for gstreamer include support for MNGs and all sorts of AVIs, which should be sufficient.

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

QMC2 can handle previews, flyers and icons stored in directories or ZIP archives.

Every image file (or ZIP member) must be named exactly as the corresponding 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 true for image directories as well, with the exception of previews: to support the direct use of in-game screenshots created with MAME/MESS, QMC2 also tries to find preview images in sub-directories of the preview-directory 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 preview-directory before. Note that for this to work, it is also required to setup the snapshot_directory of MAME/MESS to the directory where your previews are stored! See Emulator -> Global configuration in the setup dialog to synchronize that.

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!

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 previews & flyers directory based. Icons are usually small, so reading one big file at once is much faster than reading many little files. In contrast to previews or flyers which are loaded on demand (and stored in a least recently used cache), icons will be pre-loaded in one step, so it has major impact on the startup performance of QMC2.

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.

Another possibility is to synchronize both configurations (standalone & QMC2) by either exporting or importing the respective global configuration file (mame.ini). In this case you should also take care of the inipath parameter which points to the directory where MAME/MESS searches for ini-files. For example, if you setup the inipath to ~/.qmc2/ini a shell alias like

    $ alias mame="mame -inipath ~/.qmc2/ini"

could make life easier for you, and MAME/MESS would always look the same (provided you keep mame.ini/mess.ini in synch with QMC2's MAME/MESS configuration => export it every time you change it). This is also true when a game/machine-specific configuration (gamename.ini) is used, whose parameters will overwrite those of the global configuration (mame.ini).

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 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.2.b6 Qt 4.3 is no longer supported - upgrade to Qt 4.4+ 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 potentionally 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 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.

See also Q2.8.

Q2.11: When I try to launch another QMC2 variant from a currently running one, nothing happens. What's up?

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 to run the following command:

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

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

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

The runonce utility is used 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, 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 involved signalling 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 caused 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 on 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.

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

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: 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: 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 setup correctly
   Solution: Check the rompath-setting in your global emulator options (see Tools -> Options -> Emulator -> Global configuration)!
   For SDLMAME or SDLMESS see Search paths.
   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/)

This answer is obsolete: as of v0.2.b6 Qt 4.3 is no longer supported - upgrade to Qt 4.4+ 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.2.b6 Qt 4.3 is no longer supported - upgrade to Qt 4.4+ 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 is a known bug of Qt on that platform. It only happens to PNG images that are embedded into the application in the form of a Qt resource. Unfortunately, QMC2 uses only PNG images and most of them are embedded (all static icons), so the bug may concern everyone running on a PPC Linux system!

A bug report has already been filed at Qt Software's bug tracking system and chances are it will sooner or later be fixed by the former Trolls... anyway, other than a somewhat unusual look'n'feel it doesn't really harm and QMC2 will run fine on this platfom :)!