Go to the first, previous, next, last section, table of contents.

6 Settings and resources

In the VICE emulators, all the settings are stored in entities known as called resources. Each resource has a name and a value which may be either an integer or a string. Integer values are often used as boolean values with the usual convention of using zero for "false" and any other value for "true".

Resource values can be changed via the right-button menu (the settings menu), via command-line options or via the resource file.

The resource file is a human-readable file containing resource values: it is called `vicerc' and is stored in the directory `.vice/' in the user's home directory. It is possible to dump the current values of the resources into that file or load the values stored into that file as the current values, at any time. This is achieved with the "Save settings" and "Load settings" right menu items. A third menu item, "Restore Default Settings", can be used to reset all the values to the factory defaults.

A special resource, SaveResourcesOnExit, if set to a non zero value, causes the emulator to ask you if you want to save the current (changed) settings before exiting, and can be toggled with the "Save settings on exit" command from the right-button menu.

Notice that not all the resources can be changed from the menus; some of them can only be changed by manually modifying the resource file or by using command-line options.

6.1 Format of resource files

A resource file is made up of several sections; sections have the purpose of separating the resources of a certain emulator from the ones of the other emulators. A section starts with the name of an emulator in brackets (e.g., `[C64]') and ends when another section starts or when the file ends.

Every line in a section has the following format:

RESOURCE=VALUE

where RESOURCE is the name of a resource and VALUE is its assigned value. Resource names are case-sensitive and resource values are either strings or integers. Strings must start and end with a double quote character ("), while integers must be given in decimal notation.

Here is an example of a stripped-down `.vice/vicerc' file:

[VIC20]
HTMLBrowserCommand="netscape %s"
SaveResourcesOnExit=0
FileSystemDevice8=1
FSDevice8ConvertP00=1
FSDevice8Dir="/home/ettore/cbm/stuff/vic20p00"
FSDevice8SaveP00=1
FSDevice8HideCBMFiles=1
[C64]
HTMLBrowserCommand="netscape %s"
SaveResourcesOnExit=1
FileSystemDevice8=1
FSDevice8ConvertP00=1
FSDevice8Dir="/home/ettore/cbm/stuff/c64p00"
FSDevice8SaveP00=1
FSDevice8HideCBMFiles=1

Notice that, when resource values are saved with "Save settings", the emulator only modifies its own section, leaving the others unchanged.

6.2 Using command-line options to change resources

Resources can also be changed via command-line options.

Command-line options always override the defaults from .vice/vicerc, and their assignments last for the whole session. So, if you specify a certain command-line option that changes a certain resource from its default value and then use "Save Settings", the value specified with the command-line option will be saved back to the resource file.

Command-line options can begin with with a minus sign (`-') or with a plus sign (`+'). Options beginning with a minus sign may require an additional parameter, while the ones beginning with the plus sign never require one.

Moreover, options beginning with a plus sign always have a counterpart with the same name, but with a minus sign; in that case, the option beginning with a minus sign is used to enable a certain feature, while the one beginning with a plus sign is used to disable the same feature (this is an X11 convention). For example, -mitshm enables support of MITSHM, while +mitshm disables it.

6.3 Autostart settings

6.3.1 Autostart resources

AutostartPrgDiskImage: String specifying the filename of the disk image used when autostarting a prg file and "copy to D64" is enabled.
AutostartBasicLoad: Boolean, if true load to basic start using ,8 when autostarting.
AutostartRunWithColon: Boolean, if true put a colon after the load command when autostarting.
AutostartHandleTrueDriveEmulation: Boolean, if true handle (enable/disable) True Drive Emulation on autostart.
AutostartWarp: Boolean, if true temporarily enable warp mode when autostarting
AutostartPrgMode: Integer specifying the autostart mode for prg files. (0: virtual filesystem, 1: inject to RAM, 2: copy to D64)
AutostartDelayRandom: Boolean, enables a short random delay on autostart.
AutostartDelay: Integer specifying the maximum delay in frames.

6.4 Performance settings

It is possible to control the emulation speed by using the "Maximum speed" menu item in the right-button menu. The default setting is 100, which causes the emulation to never run faster than the real machine. A higher value allows the emulator to run faster, a lower one may force it to run slower. The setting "No limit" means to run as fast as possible, without limiting speed.

It is also possible to control the emulator's rate of frame update using the "Refresh rate" setting; the value ranges from "1/1" (update 1/1 of the frames of the real machine, that is 50 frames per second) to "1/10" (update 1 every 10 frames) and can be changed via the "Refresh Rate" submenu. The "Auto" setting means to dynamically adapt the refresh rate to the current speed of the host machine, making sure the maximum speed specified by the via "Maxium speed" is always reached if possible. In any case, the refresh rate will never be worse than 1/10 if this option is specified.

Note that you cannot simultaneously specify "Auto" as the refresh rate and "No limit" as the maximum speed..

Moreover, a special warp speed mode is provided and can be toggled with the "Enable Warp Mode" menu item. If this mode is enabled, it will cause the emulator to disable any speed limit, turn sound emulation off and use a 1/10 refresh rate, so that it will run at the maximum possible speed.

6.4.1 Performance resources

Speed: Integer specifying the maximum relative speed, as a percentage. 0 stands for "no limit".
RefreshRate: Integer specifying the refresh rate; a value of n specifies a refresh rate of 1/n. A value of 0 enables automatic frame skipping.
WarpMode: Booolean specifying whether "warp mode" is turned on or not.

6.4.2 Performance command-line options

-speed VALUE: Specifies the maximum speed as a percentage. 0 stands for "no limit". (Same as setting the Speed resource.)
-refresh VALUE: Specifies refresh rate; a value of n specifies a refresh rate of 1/n. A value of 0 enables automatic frame skipping. (Same as setting the RefreshRate resource.)
-warp
+warp: Enables/disables warp mode (WarpMode=1, WarpMode=0).

6.5 Video settings

The following right-button menu items control the video output. On emulators that include two video chips (like x128) all options but XSync exist twice, once for each chip. XSync is shared between the video chips.

"Video Cache" enables a video cache that can speed up the emulation when little graphics activity is going on; it is especially useful when you run the emulator on a networked X terminal as it can reduce the network bandwidth required. However, this setting can actually make the emulator slower when there is little graphics activity and the amount of work needed to maintain the cache is greater than the amount of work that would be wasted by not using it (if any).
"Double Size" toggles double-size mode, which makes the emulation window twice as big. When emulating a 80-column PET, only the height is doubled, so that the aspect ratio is closer to that of the real thing.
"Double Scan" toggles double-scan mode, which causes the emulator to draw only odd lines when running in double-size mode (this saves some CPU time and also makes the emulation window look more like an old monitor).
`Use XSync()" causes the emulator to call the X11 function XSync() before updating the emulation window: this might be necessary on low-end systems to prevent it from consuming so many system resources that it becomes impossible for the user to interact with it.

6.5.1 using openGL Rastersynchronization under X11

Warning: To get full retro experience with synchronization to the vertrical raster retrace messing with X11 modelines (resolution and refresh frequencies) is necessary. This description is a suggestion - Follow this instructions at your own risk!

The following was tested under Ubuntu Linux (8.04) featuring Xorg Xserver 1:7.3+10ubuntu and mesa openGL including HW support (NVIDIA driver) supporting glx version 1.4 supplying GLX_SGI_video_sync.

It is assumed that this works also on other systems supporting the required extensions.

Preconditions:

openGL extension GLX_SGI_video_sync in your X11 setup. The availability of the extension is checked at startup.
XRandR extension to switch proper modes (50Hz for PAL, 60Hz for NTSC) is mandatory, proper modelines in your /etc/X11/xorg.conf must be present.

If your systems lacks 50 or 60Hz modes you might try using `gtf' (typcally shipped with Xorg, xserver) - see related man page.

You might need to add the output such as:

# 800x600 # 50.00 Hz (GTF) hsync: 30.90 kHz; pclk: 31.15 MHz
Modeline "800x600_50.00" 31.15 800 824 904 1008 600 601 604 618 -HSync +Vsync

to you Monitor Section of /etc/X11/xorg.conf and add the resolution to the `Screen' section.

Sometimes some consistency checks within the display driver drop this resolutions again. To drop e.g. the autodetection features in the NVIDIA driver you might add Option "UseEDID" "FALSE" in section Device.

XRandR cannot cope properly with the DynamicTwinView feature of the proprietary nvidia driver. You might need

Option "DynamicTwinView" "False"

to get proper results (in Screen or Device section of you xorg.conf).

ATTENTION: Disabling such features might allow X11 to access your HW in a way that it gets damaged! You are at your own risk!

Enable fullscreen (not necessary, but makes sense):

choose your preferred resolution/refresh XRandR Resolutions and enable XRandR as fullscreen device (50Hz/PAL or 60Hz/NTSC mode).
Activate fullscreen with `Alt-D'.
choose `OpenGL Rastersynchronization' in the video chip menu (VIC-II Settings, VIC Setting, etc.)

Note that:

the current implementation is dropping synchronization silently in case the display frequency isn't aligned (50Hz for PAL, 60Hz for NTSC).
On some systems the XRandR system isn't informed about desktop display frequency changes if you switch resolutions via hotkeys like CTRL-Alt-+ (Numpad), which is possible e.g. with the X11 implementation of Xorg. In that case you can override/tell the current frequency via menu: Settings->VICII Settings->Desktop Refreshrate (e.g. in x64) (this shouldn't be necessary if you use fullscreen via XRandR.

6.5.2 Video resources

The following resources affect the screen emulation.

UseXSync: Boolean specifying whether XSync() is called after updating the emulation window.
MITSHM: Integer specifying whether VICE should try to use the shared memory extensions (MITSHM) when starting up. The shared memory extensions make things a lot faster but might not be available on your system. You will not be able to use these extensions if you are sitting at an X terminal while running the emulator on a remote machine across a network. Valid values are: 0 = do not use MITSHM, 1 = do use MITSHM, -1 = try to autodetect availability on startup (default). The last is a simple test if the emulator runs across a network and if so disables MITSHM (If you have problems with this test please report it).
PrivateColormap: Boolean specifying whether VICE should install a private colormap at startup. This makes sense for 8-bit displays that could run out of colors if other color-hungry applications are running at the same time.
DisplayDepth: Integer specifying the depth of the host display. The value `0' (the default) causes the emulator to autodetect it.
UseFullscreen: Boolean specifying whether fullscreen mode is currently in use.
HwScalePossible: Boolean that indicates whether hardware scaling is possible or not.
openGL_sync: Boolean, if true enable Open-GL frame sync.
openGL_no_sync: Boolean, if true Open-GL sync is not available.
KeepAspectRatio: Boolean specifying whether the aspect ratio of the output window should be preserved. (0=free scaling, 1=scale with fixed aspect ratio)
TrueAspectRatio: Boolean specifying whether to use the true (non square pixels) aspect ratio.
Window0Width
Window0Height
Window0Xpos
Window0Ypos: Integers specifying the position and size of the (first) emulator window.
Window1Width
Window1Height
Window1Xpos
Window1Ypos: Integers specifying the position and size of the (second) emulator window.

6.5.3 Video command-line options

-xsync
+xsync: Enable/disable usage of XSync() when updating the emulation window (UseXSync=1, UseXSync=0).
-mitshm
+mitshm: Enable/disable usage of the MITSHM extensions (MITSHM=1, MITSHM=0).
-install
+install: Enable/disable installation of a private colormap (PrivateColormap=1, PrivateColormap=0).
-displaydepth DEPTH: Specify the display depth (DisplayDepth).
-fullscreen
+fullscreen: Enable/disable fullscreen mode

6.6 Keyboard settings

It is possible to specify whether the "positional" or "symbolic" keyboard mapping should be used with the "Keyboard mapping type" submenu (see section 2.8 The keyboard emulation for an explanation of positional and symbolic mappings).

The keyboard settings submenu also allows you to:

Load custom-made positional and symbolic keymap files ("Set symbolic keymap file" and "Set positional keymap file").
Dump the current keymap to a user-defined keymap file ("Dump to keymap file").

6.6.1 Keyboard resources

KeymapIndex: Integer identifying which keymap is being used; 0 indicates symbolic mapping, 1 positional mapping. For the PET the even values represent symbolic mapping, odd positional. Then add 0 for UK business keyboard or 2 for graphics keyboard.
KeymapSymFile: String specifying the name of the keymap file for the symbolic mapping (see section 2.8 The keyboard emulation, all but PET and CBM-II).
KeymapSymDeFile: String specifying the name of the keymap file for the symbolic mapping (de)
KeymapPosFile: String specifying the name of the keymap file for the positional mapping (see section 2.8 The keyboard emulation, all but PET and CBM-II).
KeymapBusinessUKSymFile
KeymapBusinessUKPosFile: String specifying the name of the keymap file for the symbolic and positional mapping for the UK business keyboard (see section 2.8 The keyboard emulation, PET and CBM-II).
KeymapGraphicsSymFile
KeymapGraphicsPosFile: String specifying the name of the keymap file for the symbolic and positional mapping for the graphics keyboard (see section 2.8 The keyboard emulation, PET only).
KeymapBusinessDESymFile
KeymapBusinessDEPosFile: String specifying the name of the keymap file for the symbolic and positional mapping for the German business keyboard. (see section 2.8 The keyboard emulation, PET only).

6.6.2 Keyboard command-line options

-keymap N: Specifies which keymap is being used; 0 indicates symbolic mapping, 1 positional mapping (as for the KeymapIndex resource).
-symkeymap NAME: Specify `NAME' as the symbolic keymap file (KeymapSymFile).
-poskeymap NAME: Specify `NAME' as the positional keymap file (KeymapPosFile).
-symdekeymap NAME: Specify `NAME' as the symbolic keymap file (KeymapSymDeFile).
-buksymkeymap NAME
-bukposkeymap NAME: Specify `NAME' as the symbolic/positional keymap file for the UK business keyboard (KeymapBusinessUKSymFile, KeymapBusinessUKPosFile, PET and CBM-II).
-grsymkeymap NAME
-grposkeymap NAME: Specify `NAME' as the symbolic/positional keymap file for the graphics keyboard (KeymapGraphicsSymFile, KeymapGraphicsPosFile, PET only).
-bdesymkeymap NAME
-bdeposkeymap NAME: Specify `NAME' as the symbolic/positional ke