cap32(6)

NAME
cap32 - Caprice32 Amstrad CPC emulator

SYNOPSIS
cap32 [OPTION]... [FILE]...

DESCRIPTION
Caprice32 is an Amstrad CPC emulator. It emulates the Amstrad CPC464, 664, 6128 and 6128+ home computers.

Media loading
    Upon invocation, the FILEs specified as arguments will be used to populate the various available CPC machine slots. The type of slot is determined by the file format, detected by its extension. Caprice32 supports the following file formats: .dsk (disk image), .ipf (Interchangeable Preservation Format disk image), .voc or .cdt (tape image), .cpr (cartridge image), .sna (snapshot image), .zip (zip of any previously described file). Specifying slot content on the command line is optional.

    Caprice32 supports two disk drives: drive A and drive B. If two disk image files (.dsk or .ipf) are provided, the first one will be loaded in drive A and the second one in drive B.

    The cart_path, snap_path, dsk_path and tape_path entries in the configuration file are only used to specify the directory to open when loading/saving files in the GUI. The full path to the various slot contents must be provided on the command line.

    The rom_path entry in the configuration file is used by the emulator to find its system ROM and cartridges.

Configuration
    When launched, Caprice32 will look for a configuration file in several locations. If a configuration file was specified using the --cfg_file command line switch, Caprice32 will try and use it. If no configuration file was specified, or the configuration file specified does not exist, Caprice32 will try and open, in this order:
      - $CWD/cap32.cfg ($CWD being the directory where the cap32 executable resides)
      - cap32.cfg file in the location pointed to by the XDG_CONFIG_HOME environment variable. If XDG_CONFIG_HOME is undefined, it will look at $HOME/.config/ as default XDG_CONFIG_HOME directory.
      - $HOME/.cap32.cfg for compatibility.
      - /etc/cap32.cfg.
    Caprice32 will use the first valid file it finds. If no configuration file is found, a default configuration will be used.

    The configuration file contains various configuration parameters, some of which can be modified from the GUI. When saving the configuration from the GUI, it will be written in the configuration file following the same order than previously described, except for the addition of the write permission condition.

    Most of the configuration file entries are commented in the configuration file provided by default with Caprice32. However, when overwriting the configuration file from the emulator menu, all comments will be lost.

Control
    Emulator functionalities are available through function keys (F1-F12). As CPC also had function keys, those are emulated by keys from the numpad. This makes sense since their disposition on the CPC keyboard was similar to the numpad. If your computer doesn't have a numpad (e.g laptop that doesn't support it with Fn key) the only way to access the CPC F1-F10 keys is through the virtual keyboard. The emulator function key mapping can also be redefined through the host keyboard mapping file.

    The emulator function default key mapping is:
        F1 - Show GUI (and pause the emulator)
        F2 - Toggle fullscreen / windowed mode
        F3 - Take screenshot
        F4 - Press tape reader play key
        F5 - Reset the emulator
        F6 - Multiface II stop (advanced users only)
        F7 - Toggle joystick emulation
        F8 - Toggle FPS display
        F9 - Toggle speed limitation
        F10 - Exit the emulator
        F12 - Toggle debug mode
        Shift+F1 - Show virtual keyboard
        Shift+F3 - Take a machine snapshot

Joystick support
    Joystick emulation can be turned on with the F7 key. When joystick emulation is on, real joysticks are disabled, and the keyboard arrows (directions) as well as X and Z (fire buttons) keys are remapped to emulate the joystick 1 of the CPC machine.

    Caprice32 can also be controlled completely from the joystick. The configuration file joystick_menu_button and joystick_vkeyboard_button entries allow binding menu and virtual keyboard invocations to some of the (host) joystick button.

Keyboard mapping
    Caprice32 supports CPC English, French and Spanish keyboard layouts. The CPC keyboard layout is defined in the configuration file by the keyboard entry (0: English, 1: French, 2: Spanish). The host keyboard mapping is defined in a specific file, allowing to remap any host key to any specific key. The mapping file to use is set by the kbd_layout configuration entry. The mapping file must be put in the resources directory, defined by the configuration file resources_path entry. If the mapping file is not defined or not found, Caprice32 will default to a standard US keyboard map.

OPTIONS

-a, --autocmd=COMMAND
    pass command to execute to the emulator. The option can be repeated to pass multiple commands. For example: cap32 -a 'print "Hello"' -a 'print "World"'

-c, --cfg_file=FILE
    use FILE as the emulator configuration file.

-h, --help
    display short help and exits

-i, --inject
    inject a binary in memory after the CPC startup finishes

-o, --offset
    offset at which to inject the binary provided with -i (default: 0x6000)

-O, --override
    override an option from the config. Can be repeated. (example: -O system.model=3)

-s, --sym_file=file
    use <file> as a source of symbols and entry points for disassembling in developers' tools.

-V, --version
    display Caprice32 version and exits

-v, --verbose
    be talkative about what the emulator is doing (mostly for debug builds)

EXAMPLES

cap32 ./disk/sorcery.dsk ./trail.dsk
    Launches cap32, loads the content of ./disk/sorcery.dsk in the drive A slot, and ./trail.dsk in the drive B slot.

BUGS
CPC6128+ emulation is incomplete: vectored & DMA interrupts, analog joysticks and 8 bit printer are not emulated.

See https://github.com/ColinPitrat/caprice32/issues for the list of reported bugs.

AUTHOR

Caprice32 was originally written by Ulrich Doewich.

This manual page covers Colin Pitrat's fork of Caprice32.

The screen capture code uses driedfruit SDL_SavePNG code (https://github.com/driedfruit/SDL_SavePNG).

FILES
$HOME/.cap32.cfg
/etc/cap32.cfg

SEE ALSO
https://github.com/ColinPitrat/caprice32
https://github.com/driedfruit/SDL_SavePNG