| 1 |
<!DOCTYPE html> |
| 2 |
<html lang="en"> |
| 3 |
<head> |
| 4 |
<meta charset="utf-8"> |
| 5 |
<link title="Purple" rel="stylesheet" href="manual-purple.css" type="text/css"> |
| 6 |
<link title="Minty" rel="alternate stylesheet" href="manual-minty.css" type="text/css"> |
| 7 |
<link title="Plain" rel="alternate stylesheet" href="manual.css" type="text/css"> |
| 8 |
<title>openMSX User's Manual</title> |
| 9 |
</head> |
| 10 |
|
| 11 |
<body> |
| 12 |
|
| 13 |
<h1>openMSX User's Manual</h1> |
| 14 |
|
| 15 |
<h2>Contents</h2> |
| 16 |
|
| 17 |
<ol class="toc"> |
| 18 |
<li><a class="internal" href="#intro">1. Introduction</a> |
| 19 |
<ol class="toc"> |
| 20 |
<li><a class="internal" href="#newver">1.1 New Versions of This Document</a></li> |
| 21 |
<li><a class="internal" href="#purpose">1.2 Purpose</a></li> |
| 22 |
<li><a class="internal" href="#history">1.3 Revision History</a></li> |
| 23 |
<li><a class="internal" href="#terms">1.4 Important Terms</a></li> |
| 24 |
</ol> |
| 25 |
</li> |
| 26 |
<li><a class="internal" href="#starting">2. Starting the Emulator</a> |
| 27 |
<ol class="toc"> |
| 28 |
<li><a class="internal" href="#machines">2.1 Machines</a></li> |
| 29 |
<li><a class="internal" href="#extensions">2.2 Extensions</a></li> |
| 30 |
<li><a class="internal" href="#otheroptions">2.3 Other Command-line Options</a></li> |
| 31 |
</ol> |
| 32 |
</li> |
| 33 |
<li><a class="internal" href="#controlling">3. The Console and Settings</a> |
| 34 |
<ol class="toc"> |
| 35 |
<li><a class="internal" href="#console">3.1 Console Introduction</a></li> |
| 36 |
<li><a class="internal" href="#importantconsole">3.2 Some Simple Console Commands</a></li> |
| 37 |
<li><a class="internal" href="#settings">3.3 Settings</a></li> |
| 38 |
<li><a class="internal" href="#plug">3.4 Plugging in devices in connectors</a></li> |
| 39 |
</ol> |
| 40 |
</li> |
| 41 |
<li><a class="internal" href="#gui">4. The Graphical User Interface</a> |
| 42 |
<ol class="toc"> |
| 43 |
<li><a class="internal" href="#guioverview">4.1 Overview</a></li> |
| 44 |
<li><a class="internal" href="#guimainmenu">4.2 Main menu bar</a></li> |
| 45 |
<li><a class="internal" href="#guiother">4.3 Other default GUI elements</a></li> |
| 46 |
<li><a class="internal" href="#guiadvanced">4.4 Advanced topics</a> |
| 47 |
<ol class="toc"> |
| 48 |
<li><a class="internal" href="#guiadvanced_tips">4.4.1 Some tips and tricks</a></li> |
| 49 |
</ol> |
| 50 |
</li> |
| 51 |
</ol> |
| 52 |
</li> |
| 53 |
<li><a class="internal" href="#media">5. Running MSX Software and Using Media</a> |
| 54 |
<ol class="toc"> |
| 55 |
<li><a class="internal" href="#roms">5.1 Running ROM Software</a></li> |
| 56 |
<li><a class="internal" href="#disks">5.2 Running Disk Software</a> |
| 57 |
<ol class="toc"> |
| 58 |
<li><a class="internal" href="#diskimages">5.2.1 Using Disk Images</a></li> |
| 59 |
<li><a class="internal" href="#dirasdisk">5.2.2 Using Directories as Disks</a></li> |
| 60 |
<li><a class="internal" href="#realdisks">5.2.3 Using Real Disks</a></li> |
| 61 |
<li><a class="internal" href="#diskmanagement">5.2.4 Managing Disk Images</a></li> |
| 62 |
</ol> |
| 63 |
</li> |
| 64 |
<li><a class="internal" href="#tape">5.3 Running Tape Software</a> |
| 65 |
<ol class="toc"> |
| 66 |
<li><a class="internal" href="#cas">5.3.1 Using CAS/TSX files</a></li> |
| 67 |
</ol> |
| 68 |
</li> |
| 69 |
|
| 70 |
<li><a class="internal" href="#harddisks">5.4 Emulating MSX Harddisks, SD interfaces and CD-ROM</a> |
| 71 |
<ol class="toc"> |
| 72 |
<li><a class="internal" href="#ide">5.4.1 Sunrise IDE</a></li> |
| 73 |
<li><a class="internal" href="#beeride">5.4.2 Beer IDE</a></li> |
| 74 |
<li><a class="internal" href="#scsi">5.4.3 SCSI devices</a></li> |
| 75 |
<li><a class="internal" href="#sd">5.4.4 MegaFlashROM SCC+ SD</a></li> |
| 76 |
</ol> |
| 77 |
</li> |
| 78 |
|
| 79 |
<li><a class="internal" href="#laserdisc">5.5 Running Laserdisc Software</a></li> |
| 80 |
</ol> |
| 81 |
</li> |
| 82 |
|
| 83 |
<li><a class="internal" href="#input">6. Input Devices</a> |
| 84 |
<ol class="toc"> |
| 85 |
<li><a class="internal" href="#keyboard">6.1 Keyboard</a> |
| 86 |
<ol class="toc"> |
| 87 |
<li><a class="internal" href="#msxkeymapping">6.1.1 MSX Key Mapping</a></li> |
| 88 |
<li><a class="internal" href="#cvkeymapping">6.1.2 ColecoVision Key Mapping</a></li> |
| 89 |
<li><a class="internal" href="#emukeymapping">6.1.3 Emulator Functions Key Mapping</a></li> |
| 90 |
<li><a class="internal" href="#keyboardlayouts">6.1.4 Keyboard Layouts</a></li> |
| 91 |
</ol> |
| 92 |
</li> |
| 93 |
<li><a class="internal" href="#joystick">6.2 Joystick</a></li> |
| 94 |
<li><a class="internal" href="#mouse">6.3 Mouse</a></li> |
| 95 |
<li><a class="internal" href="#arkanoidpad">6.4 Arkanoid Pad</a></li> |
| 96 |
<li><a class="internal" href="#trackball">6.5 Trackball</a></li> |
| 97 |
<li><a class="internal" href="#touchpad">6.6 Touchpad</a></li> |
| 98 |
<li><a class="internal" href="#magickey">6.7 Magic Key</a></li> |
| 99 |
<li><a class="internal" href="#ninjatap">6.8 Ninja Tap</a></li> |
| 100 |
<li><a class="internal" href="#tetris2dongle">6.9 Tetris II Special Edition dongle</a></li> |
| 101 |
<li><a class="internal" href="#msxpaddle">6.10 MSX Paddle</a></li> |
| 102 |
<li><a class="internal" href="#circuitdesignerdongle">6.11 Circuit Designer RD dongle</a></li> |
| 103 |
</ol> |
| 104 |
</li> |
| 105 |
|
| 106 |
<li><a class="internal" href="#video">7. Video</a> |
| 107 |
<ol class="toc"> |
| 108 |
<li><a class="internal" href="#scalers">7.1 Scalers</a></li> |
| 109 |
<li><a class="internal" href="#gamma">7.2 Gamma Correction</a></li> |
| 110 |
<li><a class="internal" href="#videoeffects">7.3 Special Effects</a></li> |
| 111 |
<li><a class="internal" href="#accuracy">7.4 Accuracy</a></li> |
| 112 |
<li><a class="internal" href="#gfx9000">7.5 GFX9000/Video 9000</a></li> |
| 113 |
<li><a class="internal" href="#recording">7.6 Video Recording</a></li> |
| 114 |
</ol> |
| 115 |
</li> |
| 116 |
|
| 117 |
<li><a class="internal" href="#audio">8. Audio</a> |
| 118 |
<ol class="toc"> |
| 119 |
<li><a class="internal" href="#audiosettings">8.1 Audio Settings</a></li> |
| 120 |
<li><a class="internal" href="#midi">8.2 MIDI</a></li> |
| 121 |
<li><a class="internal" href="#soundlogger">8.3 Recording Audio to File</a></li> |
| 122 |
</ol> |
| 123 |
</li> |
| 124 |
|
| 125 |
<li><a class="internal" href="#usefulextras">9. Useful Extras</a> |
| 126 |
<ol class="toc"> |
| 127 |
<li><a class="internal" href="#savestate">9.1 Saving/Loading the State of the Machine</a></li> |
| 128 |
<li><a class="internal" href="#reverse">9.2 Reverse</a></li> |
| 129 |
<li><a class="internal" href="#trainer">9.3 Game Trainer</a></li> |
| 130 |
<li><a class="internal" href="#debugdevice">9.4 Debug Device</a> |
| 131 |
<ol class="toc"> |
| 132 |
<li><a class="internal" href="#debugdeviceenable">9.4.1 Enabling the Debug Device</a></li> |
| 133 |
<li><a class="internal" href="#debugdeviceports">9.4.2 Output Ports</a></li> |
| 134 |
<li><a class="internal" href="#debugdevicemode1">9.4.3 Single Byte Mode</a></li> |
| 135 |
<li><a class="internal" href="#debugdevicemode2">9.4.4 Multi Byte Mode</a></li> |
| 136 |
</ol> |
| 137 |
</li> |
| 138 |
<li><a class="internal" href="#programmabledevice">9.5 Programmable Device</a> |
| 139 |
<ol class="toc"> |
| 140 |
<li><a class="internal" href="#programmabledeviceenable">9.5.1 Enabling the Programmable Device</a></li> |
| 141 |
<li><a class="internal" href="#programmabledeviceports">9.5.2 Device Ports and callbacks</a></li> |
| 142 |
</ol> |
| 143 |
</li> |
| 144 |
<li><a class="internal" href="#sdcdb">9.6 SDCC Debugger</a></li> |
| 145 |
</ol> |
| 146 |
</li> |
| 147 |
<li><a class="internal" href="#contact">10. Contact Info</a></li> |
| 148 |
</ol> |
| 149 |
|
| 150 |
|
| 151 |
<h2><a id="intro">1. Introduction</a></h2> |
| 152 |
|
| 153 |
<h3><a id="newver">1.1 New Versions of This Document</a></h3> |
| 154 |
<p> |
| 155 |
The manual for the latest openMSX release can be found on the openMSX home page: |
| 156 |
</p> |
| 157 |
<p> |
| 158 |
<a class="external" href="http://openmsx.org/manual/">http://openmsx.org/manual/</a> |
| 159 |
</p> |
| 160 |
|
| 161 |
<h3><a id="purpose">1.2 Purpose</a></h3> |
| 162 |
<p> |
| 163 |
This manual is about openMSX, the open source MSX emulator that tries to achieve |
| 164 |
near-perfect emulation by using a novel emulation model. |
| 165 |
You can find more information about openMSX on the |
| 166 |
<a class="external" href="http://openmsx.org/">openMSX home page</a>. |
| 167 |
You can also download the emulator itself from there. |
| 168 |
</p> |
| 169 |
|
| 170 |
<p> |
| 171 |
openMSX is not complete yet, which means that most things work but not all |
| 172 |
features have been implemented yet. |
| 173 |
Many emulation features are implemented, but not all of them are represented |
| 174 |
yet in the built-in Graphical User Interface. To get the most out of openMSX, |
| 175 |
we have written this guide. |
| 176 |
</p> |
| 177 |
|
| 178 |
<p> |
| 179 |
This manual tells you how you can use openMSX, once it has been installed and |
| 180 |
properly set up. You should be able to use most of the features of openMSX if |
| 181 |
you have read it. |
| 182 |
If you are only using the GUI menus of openMSX, you don't have to pay attention |
| 183 |
to the exact command and setting names. However it is still useful to read this |
| 184 |
document to find out how openMSX works and learn its terminology. |
| 185 |
</p> |
| 186 |
|
| 187 |
<p> |
| 188 |
<em>Disclaimer:</em> |
| 189 |
We do not claim this guide is complete or even correct. |
| 190 |
What you do with the information in it is entirely at your own risk. |
| 191 |
We just hope it helps you enjoy openMSX more. |
| 192 |
</p> |
| 193 |
|
| 194 |
<h3><a id="history">1.3 Revision History</a></h3> |
| 195 |
|
| 196 |
<p> |
| 197 |
For the revision history, please refer to the <a class="external" |
| 198 |
href="https://github.com/openMSX/openMSX/commits/master/doc/manual/user.html">commit log</a>. |
| 199 |
</p> |
| 200 |
|
| 201 |
<h3><a id="terms">1.4 Important Terms</a></h3> |
| 202 |
|
| 203 |
<p> |
| 204 |
First some terms. Users of real MSX computers will probably not find it hard to understand these, but we'll explain what we mean with them to make sure the terms used in openMSX are clear for everyone. |
| 205 |
<p> |
| 206 |
|
| 207 |
<dl> |
| 208 |
<dt>Machine</dt> |
| 209 |
<dd>With a machine we denote a single instance of a particular MSX computer. The bare computer, with a manufacturer name and a type name, just as they were sold.</dd> |
| 210 |
<dd>In case you're not too familiar with MSX: it's a standard, and many manufacturers created several MSX compatible computer models. openMSX tries to emulate them all and you can choose which particular brand and model you want to emulate.</dd> |
| 211 |
<dt>Extensions</dt> |
| 212 |
<dd>All standard MSX computers have cartridge slots in which extension cartridges can be plugged into. They can be anything, like external disk drives, sound cartridges, serial interfaces, video cards, and multi-cartridges like the Carnivore 2 or the MegaFlashROM SCC+ SD.</dd> |
| 213 |
<dd>Technically, a game (ROM) cartridge you put in a cartridge slot is also a form of an extension. See also below under Media.</dd> |
| 214 |
<dd>For technical reasons, some extension cartridges in openMSX do not take up a cartridge slot ("I/O only extensions").</dd> |
| 215 |
<dt>Connectors</dt> |
| 216 |
<dd>The bare MSX machine has connectors to which equipment can be plugged of which the plug matches the connector (called "pluggables" here and there).</dd> |
| 217 |
<dd>Examples are printers, joysticks, mice, dongles, MIDI equipment, ...</dd> |
| 218 |
<dd>openMSX does not allow you to plug in equipment in the wrong connector type.</dd> |
| 219 |
<dd>Some equipment is automatically plugged in for your convenience, e.g. the Tape Deck if your machine has a cassette connector.</dd> |
| 220 |
<dt>Media</dt> |
| 221 |
<dd>These are containers with software on them. For example: ROM cartridges, floppy disks, and cassette tapes.</dd> |
| 222 |
<dd>Depending on the MSX machine you are using, different media can be inserted. If the machine you are emulating does not have a disk drive, you cannot insert a floppy disk (image) into the machine. However, like in the real world, if you first insert an external disk drive extension into one of the cartridge slots of the machine, you can insert a floppy disk into the disk drive you just connected to the MSX.</dd> |
| 223 |
<dd>Media are always represented by an "image" of their content, which is just a file containing the relevant data of the media. So, a ROM cartridge is represented by a ROM file (which is just the data from the ROM chips), floppy disks by disk image files, cassette tapes with tape image files, etc. This manual may use also these "image" terms to refer to media.</dd> |
| 224 |
<dt>Setups</dt> |
| 225 |
<dd>A setup is the combination of a bare MSX machine, with its plugged-in extensions, plugged-in equipment via the machine's connectors and the media in the available media slots.</dd> |
| 226 |
<dd>When creating a new setup, you can specify up to what depth level the setup must be saved: either just the machine, or including the extensions, or also including the plugged-in equipment or even including the inserted media.</dd> |
| 227 |
<dd>The setups feature allows you like in the real world to turn off your setup and use it quickly again later.</dd> |
| 228 |
</dl> |
| 229 |
|
| 230 |
<h2><a id="starting">2. Starting the Emulator</a></h2> |
| 231 |
|
| 232 |
<p> |
| 233 |
In this chapter we will tell you how to select MSX machines and how to use extension cartridges, when starting up openMSX. |
| 234 |
</p> |
| 235 |
|
| 236 |
<h3><a id="machines">2.1 Machines</a></h3> |
| 237 |
|
| 238 |
<p> |
| 239 |
If you start openMSX without any command-line parameters, you will get the |
| 240 |
default machine, which is stored in the <code><a class="external" |
| 241 |
href="commands.html#default_machine">default_machine</a></code> setting. If you did |
| 242 |
not change the default machine, the C-BIOS MSX2+ machine will be started. |
| 243 |
</p> |
| 244 |
|
| 245 |
<p> |
| 246 |
However, if you created a setup earlier and marked it as the default setup (via the <code><a class="external" |
| 247 |
href="commands.html#default_setup">default_setup</a></code> setting), that setup |
| 248 |
will be loaded instead. This can be useful to always start up with your favourite |
| 249 |
setup. |
| 250 |
</p> |
| 251 |
|
| 252 |
<p> |
| 253 |
To select machines from the GUI, click <span class="menu-reference">Main menu |
| 254 |
bar → Machine → Select MSX machine...</span> This will |
| 255 |
give a window in which you can see an overview of all available machines to |
| 256 |
select from and hovering on items in the list shows you the most important |
| 257 |
properties of these machines. You can also filter on type, region or any part |
| 258 |
of the machine names. You can replace the current machine, or run another |
| 259 |
machine along the existing running machines. An overview of the running |
| 260 |
machines is shown at the top of the machine selection window, where you can |
| 261 |
also change the default machine. |
| 262 |
</p> |
| 263 |
|
| 264 |
<p> |
| 265 |
To select a different MSX machine from the command line, you can use the |
| 266 |
<code>-machine</code> argument: |
| 267 |
</p> |
| 268 |
<div class="commandline"> |
| 269 |
openmsx -machine Panasonic_FS-A1GT |
| 270 |
</div> |
| 271 |
<p> |
| 272 |
It is also possible to use the <code><a class="external" |
| 273 |
href="commands.html#machine">machine</a></code> command to switch at run time |
| 274 |
in the <a class="internal" href="#console">console</a>, which is explained in |
| 275 |
the next chapter. |
| 276 |
</p> |
| 277 |
|
| 278 |
<p> |
| 279 |
The C-BIOS machines come with ROMs installed; for other machines you will have |
| 280 |
to install system ROMs yourself, see the <a class="external" |
| 281 |
href="setup.html#systemroms">Setup Guide</a> for details. |
| 282 |
You can always use <span class="menu-reference">Main menu bar → Machine |
| 283 |
→ Test MSX hardware</span> to verify which system ROMs have been (correctly) |
| 284 |
installed. |
| 285 |
</p> |
| 286 |
|
| 287 |
<p> |
| 288 |
If you have saved a setup earlier (using the GUI via <span class="menu-reference">Main menu bar |
| 289 |
→ Machine → Save setup</span> or the <code><a class="external" |
| 290 |
href="commands.html#store_setup">store_setup</a></code> command) you can also use the GUI via <span class="menu-reference">Main menu |
| 291 |
bar → Machine → Load setup</span> to go from that setup. But also |
| 292 |
here you can use the command line (via the <code>-setup</code> command line |
| 293 |
option) or the console (via the <code><a class="external" |
| 294 |
href="commands.html#setup">setup</a></code> command). |
| 295 |
</p> |
| 296 |
|
| 297 |
<h3><a id="extensions">2.2 Extensions</a></h3> |
| 298 |
|
| 299 |
<p> |
| 300 |
Extensions are simply MSX cartridges (extensions to the MSX system) that you |
| 301 |
can plug into the emulated MSX. openMSX ships with many predefined |
| 302 |
extensions. Note that many of them require firmware ROMs (called system ROMs); |
| 303 |
see the <a class="external" href="setup.html#systemroms">Setup Guide</a> for |
| 304 |
details. |
| 305 |
</p> |
| 306 |
|
| 307 |
<p> |
| 308 |
Using the GUI, use the <span class="menu-reference">Main menu bar → |
| 309 |
Media</span> menu where you can either first select the MSX cartridge slot to |
| 310 |
put the extension into, or directly select the <span class="menu-reference">Extensions</span> menu option to insert |
| 311 |
an extension in the first free slot or remove extensions from the slot they're |
| 312 |
in. |
| 313 |
</p> |
| 314 |
|
| 315 |
<p> |
| 316 |
Let's now go into details using the FMPAC as an example. openMSX ships with a |
| 317 |
definition (XML file) for the FMPAC extension, but you will have to <a |
| 318 |
class="external" href="setup.html#installrom">add</a> the |
| 319 |
<code>fmpac.rom</code> firmware ROM yourself. When you have done so, you can |
| 320 |
insert an FMPAC into the emulated MSX machine with the following command line: |
| 321 |
</p> |
| 322 |
<div class="commandline"> |
| 323 |
openmsx -ext fmpac |
| 324 |
</div> |
| 325 |
<p> |
| 326 |
Similar to machines, you can also use the <code><a class="external" |
| 327 |
href="commands.html#ext">ext</a></code> command in the console to do it at run |
| 328 |
time. You can also use something like <code>-extb</code> to explicitly specify |
| 329 |
cartridge slot B. |
| 330 |
</p> |
| 331 |
|
| 332 |
<p> |
| 333 |
If you look in the <code>share/extensions</code> directory (or when using the |
| 334 |
console, type the TAB key with the <code>ext</code> command, see next chapter), |
| 335 |
you will see all the extensions known to openMSX. For example <code>-ext |
| 336 |
mbstereo</code> gives you the MoonBlaster stereo effect: FMPAC on the left |
| 337 |
speaker and MSX-AUDIO on the right speaker. |
| 338 |
</p> |
| 339 |
|
| 340 |
<h3><a id="otheroptions">2.3 Other Command-line Options</a></h3> |
| 341 |
|
| 342 |
<p> |
| 343 |
Some of the most used command-line options will be discussed later in this manual. |
| 344 |
For a complete list of them, type the following command: |
| 345 |
</p> |
| 346 |
<div class="commandline">openmsx -h</div> |
| 347 |
|
| 348 |
<h2><a id="controlling">3. The Console and Settings</a></h2> |
| 349 |
|
| 350 |
<h3><a id="console">3.1 Console Introduction</a></h3> |
| 351 |
|
| 352 |
<p> |
| 353 |
Most functionality can now be controlled via the built-in GUI, using the |
| 354 |
main menu bar as a starting point. This will be sufficient for most users. |
| 355 |
Originally, this GUI wasn't available and most functionality had to be |
| 356 |
controlled differently. This way of control is still available (and will remain |
| 357 |
so); this section will tell you more about it. You don't need to care about any |
| 358 |
of these commands if the GUI is sufficient for you, but we still recommend having a look at the sections about "Settings" |
| 359 |
and "Plugging in devices in connectors". |
| 360 |
</p> |
| 361 |
|
| 362 |
<p> |
| 363 |
openMSX has a built-in command interface called the <em>console</em>, |
| 364 |
which allows you to control almost all aspects of openMSX while it is running. |
| 365 |
To access the console, make sure to have the main emulator window selected, and then press F10 |
| 366 |
(with <a class="internal" href="#keymapping">default key mapping</a>; Cmd+L on |
| 367 |
Mac). This will |
| 368 |
open a window with a command line inside the main openMSX window. |
| 369 |
</p> |
| 370 |
|
| 371 |
<p> |
| 372 |
Typing <a class="external" href="commands.html#help"><code>help</code></a> |
| 373 |
gives a list of commands. Using PageUp you can see all of them. If you type |
| 374 |
<code>help [command]</code> you will get help for the specified command. This |
| 375 |
manual describes a few important commands; a full list can be found in the <a |
| 376 |
class="external" href="commands.html">Console Command Reference</a>. The |
| 377 |
console can be used to <a class="internal" href="#disks">change disk |
| 378 |
images</a>, plug in <a class="internal" href="#joystick">joysticks</a> or <a |
| 379 |
class="internal" href="#mouse">mice</a>, <a class="internal" |
| 380 |
href="#settings">change settings</a> at run time and to change key bindings, |
| 381 |
among others. It actually gives you full control of openMSX: if it can't be |
| 382 |
done via the console, it's probably impossible! |
| 383 |
</p> |
| 384 |
|
| 385 |
<p> |
| 386 |
One very practical feature of the console command line is that you can use |
| 387 |
"completion" features. Just try typing half a command and then press the TAB |
| 388 |
key; openMSX will then try to finish the word you were typing or show the |
| 389 |
possibilities in case of ambiguities. You can use it also for file names, |
| 390 |
connectors, pluggables and settings, and even for machine and extension names. |
| 391 |
</p> |
| 392 |
|
| 393 |
<p>The console has very common keyboard controls, similar to most text editors. |
| 394 |
It also supports copy/paste. Some other controls may be less obvious: </p> |
| 395 |
|
| 396 |
<table> |
| 397 |
<tr> <th>key(s) </th> <th>function </th> </tr> |
| 398 |
<tr> <td>Up </td> <td>show previous command from history (starting with current command line)</td> </tr> |
| 399 |
<tr> <td>Down </td> <td>show next command from history (starting with current command line) </td> </tr> |
| 400 |
<tr> <td>Tab </td> <td>attempt completion of current command </td> </tr> |
| 401 |
<tr> <td>Enter/Return </td> <td>execute command line </td> </tr> |
| 402 |
</table> |
| 403 |
|
| 404 |
<h3><a id="importantconsole">3.2 Some Simple Console Commands</a></h3> |
| 405 |
|
| 406 |
<p> |
| 407 |
You can reset your MSX with the console command <code><a class="external" |
| 408 |
href="commands.html#reset">reset</a></code> and exit openMSX with the command |
| 409 |
<code><a class="external" href="commands.html#exit">exit</a></code>. As |
| 410 |
explained in the previous chapter, you can change machines with the <code><a |
| 411 |
class="external" href="commands.html#machine">machine</a></code> command and |
| 412 |
you can insert extensions with the <code><a class="external" |
| 413 |
href="commands.html#ext">ext</a></code> command (use tab-completion to see the |
| 414 |
list of possible extension names). Remove extensions with the <code><a |
| 415 |
class="external" |
| 416 |
href="commands.html#remove_extension">remove_extension</a></code> command or |
| 417 |
get a list of the currently inserted extensions with the <code><a |
| 418 |
class="external" |
| 419 |
href="commands.html#list_extensions">list_extensions</a></code> command. Other |
| 420 |
commands will be discussed later on in this manual. |
| 421 |
</p> |
| 422 |
|
| 423 |
<h3><a id="settings">3.3 Settings</a></h3> |
| 424 |
|
| 425 |
<p> |
| 426 |
There are many settings in openMSX for customization, changing preferences or |
| 427 |
enabling extras. The most important ones are in the <span |
| 428 |
class="menu-reference">Main menu bar → Settings</span> menu in the GUI. |
| 429 |
There is also an Advanced item in that menu that will give a huge window with |
| 430 |
all possible settings. Usually, you can revert a setting to its default value |
| 431 |
via <span class="menu-reference">right click → Restore default</span> in |
| 432 |
the context-menu of that setting. |
| 433 |
</p> |
| 434 |
|
| 435 |
<p> |
| 436 |
Using the console, you can use the command <code><a class="external" |
| 437 |
href="commands.html#set">set</a></code> to change any setting. E.g., you can |
| 438 |
use it to set the current <a class="internal" href="#scalers">scaler</a>. Issuing |
| 439 |
<code>set</code> with only the setting name (like <code>set <a class="external" |
| 440 |
href="commands.html#scale_algorithm">scale_algorithm</a></code>), queries |
| 441 |
the current value of that setting. |
| 442 |
Settings that have only two possible values can also be toggled with the |
| 443 |
<code><a class="external" href="commands.html#toggle">toggle</a></code> |
| 444 |
command (an example is the default key binding of F11 to <code>toggle |
| 445 |
fullscreen</code>, see also below). A (hopefully) complete list of settings can |
| 446 |
also be found in the <a class="external" href="commands.html">Console Command |
| 447 |
Reference</a>. Note that using the "tab completion" feature can help you a lot |
| 448 |
in getting an idea of what settings are possible, as it will only complete |
| 449 |
possible options. Just try that. |
| 450 |
</p> |
| 451 |
|
| 452 |
<p> |
| 453 |
Let's give a few examples of common settings and how to change them. |
| 454 |
</p> |
| 455 |
|
| 456 |
<p> |
| 457 |
If the MSX goes too fast or too slow, adjust the emulation speed with the |
| 458 |
<code><a class="external" href="commands.html#speed">speed</a></code> setting, |
| 459 |
which has the speed percentage as parameter. So, typing <code>set |
| 460 |
speed 120</code>, will run the emulated MSX at 120% of normal MSX speed. |
| 461 |
This is useful for debugging purposes (slow down) or when you want to skip |
| 462 |
certain parts of a demo for example (speed up). The GUI has this setting under |
| 463 |
<span class="menu-reference">Main menu bar → Settings → Speed → Emulation</span>. |
| 464 |
</p> |
| 465 |
|
| 466 |
<p> |
| 467 |
Some MSX machines like the Panasonic FS-A1GT have built-in software (called |
| 468 |
firmware) which can be switched on and off via a switch on the machine itself. |
| 469 |
In openMSX the internal software is switched off by default, but you can switch |
| 470 |
it on with the following setting: <code>set <a class="external" |
| 471 |
href="commands.html#firmwareswitch">firmwareswitch</a> on</code>. If the |
| 472 |
currently running machine has a firmware switch, a toggle option will show up in |
| 473 |
the <span class="menu-reference">Main menu bar → Machine</span> menu to control it. |
| 474 |
</p> |
| 475 |
|
| 476 |
<p> |
| 477 |
If you're not really interested in how long a real MSX would take to load |
| 478 |
from diskette, cassette or laserdisc, you could enable the full speed when |
| 479 |
loading feature: <code>set <a class="external" |
| 480 |
href="commands.html#fullspeedwhenloading">fullspeedwhenloading</a> on</code>, |
| 481 |
or from the GUI at <span class="menu-reference">Main menu bar → Settings |
| 482 |
→ Speed → Go full speed when loading</span>. It |
| 483 |
runs openMSX at maximum speed whenever it thinks that the MSX is loading. The |
| 484 |
drawbacks: it might detect a bit too late that the MSX isn't loading anymore, |
| 485 |
so sometimes the first notes of music played right after loading might be |
| 486 |
fast. Also, when loading openMSX will use all available CPU power to get |
| 487 |
maximum speed; the feature has no influence on the state of the MSX, of course. |
| 488 |
</p> |
| 489 |
|
| 490 |
<p> |
| 491 |
You can save all your current settings with the <code><a class="external" |
| 492 |
href="commands.html#save_settings">save_settings</a></code> command. At start |
| 493 |
up, alternative settings files can be loaded by using the <code>-setting</code> |
| 494 |
command-line option. You can also use the <code><a class="external" |
| 495 |
href="commands.html#load_settings">load_settings</a></code> command to load |
| 496 |
settings at run time. Settings that are not mentioned in the saved settings |
| 497 |
file that you are loading will be untouched. <a class="external" |
| 498 |
href="commands.html#save_settings_on_exit">By default</a>, openMSX will |
| 499 |
automatically save your settings on exit (whichever way they were changed). |
| 500 |
</p> |
| 501 |
|
| 502 |
<h3><a id="plug">3.4 Plugging in devices in connectors</a></h3> |
| 503 |
|
| 504 |
<p> |
| 505 |
The <span class="menu-reference">Main menu bar → Connectors</span> menu |
| 506 |
will show you all connectors of the currently running |
| 507 |
machine and which (pluggable) device is currently plugged in. You can easily |
| 508 |
plug in other devices there, e.g. a mouse in a joystick port. |
| 509 |
</p> |
| 510 |
|
| 511 |
<p> |
| 512 |
Examples of connectors are the joystick ports, the printer port, the MIDI in |
| 513 |
and out connector, the cassette port, etc. Examples of pluggables are <a |
| 514 |
class="internal" href="#joystick">joysticks</a> and <a class="internal" |
| 515 |
href="#mouse">mice</a>, but also printers and MIDI equipment. |
| 516 |
</p> |
| 517 |
|
| 518 |
<p> |
| 519 |
In the console, you can use the command <code><a class="external" |
| 520 |
href="commands.html#plugunplug">plug</a></code> to do this. The command |
| 521 |
<code><a class="external" href="commands.html#plugunplug">plug</a></code> |
| 522 |
without any parameters will show a list of connectors and what pluggables are |
| 523 |
plugged into them. Using <code>plug [connector]</code> will only show what is |
| 524 |
plugged into [connector]. It will come as no surprise that the command <code>plug |
| 525 |
[connector] [pluggable]</code> will plug the [pluggable] into the [connector]. |
| 526 |
</p> |
| 527 |
|
| 528 |
<p> |
| 529 |
Note that using the "tab completion" feature can help you a lot in getting an |
| 530 |
idea of what plug commands are possible, as it will only complete possible |
| 531 |
connectors and their possible pluggables. Just give it a try. |
| 532 |
</p> |
| 533 |
|
| 534 |
|
| 535 |
|
| 536 |
|
| 537 |
|
| 538 |
|
| 539 |
|
| 540 |
<h2><a id="gui">4. The Graphical User Interface</a></h2> |
| 541 |
|
| 542 |
<h3><a id="guioverview">4.1 Overview</a></h3> |
| 543 |
|
| 544 |
<p> |
| 545 |
The Graphical User Interface (GUI) in openMSX has been built with the <a |
| 546 |
class="external" href="https://github.com/ocornut/imgui">Dear ImGui |
| 547 |
library</a>. It allows the developers to relatively easily build and extend the |
| 548 |
GUI for all supported platforms. The price we have to pay is that it only works |
| 549 |
on systems with 3D hardware acceleration support and that it does not look (a |
| 550 |
lot) like the native GUIs of well-known desktop environments like Windows, |
| 551 |
macOS, GNOME or KDE. |
| 552 |
</p> |
| 553 |
|
| 554 |
<p> |
| 555 |
General help on basic usage of the Dear ImGui features can be found in the |
| 556 |
<span class="menu-reference">Main menu bar → Help → Dear ImGui user |
| 557 |
guide</span> menu option. |
| 558 |
</p> |
| 559 |
|
| 560 |
<p> |
| 561 |
The current GUI is intended for mouse control. It can (at least |
| 562 |
partially) also be controlled with a keyboard, but so far this has not been a major focus of development, |
| 563 |
so this will definitely not be optimal. Control via a game controller is |
| 564 |
currently disabled, but that may change in future versions. |
| 565 |
</p> |
| 566 |
|
| 567 |
<p> |
| 568 |
Although the current openMSX release already has a lot of functionality |
| 569 |
available via the GUI, it is still incomplete and the user experience could use some love. We appreciate feedback on the GUI a lot and we will try to |
| 570 |
improve it in later releases based on your input. Please see section <a |
| 571 |
class="internal" href="#contact">10. Contact Info</a> for more |
| 572 |
information on how to provide feedback. |
| 573 |
</p> |
| 574 |
|
| 575 |
<p> |
| 576 |
Almost all commands and settings available in the GUI have an underlying |
| 577 |
console command and setting accessible via the console. In several places |
| 578 |
these underlying commands are mentioned in this manual. Power users especially |
| 579 |
will appreciate all the ways they can manipulate openMSX with external programs, scripts, |
| 580 |
or other more advanced methods. |
| 581 |
</p> |
| 582 |
|
| 583 |
<h3><a id="guimainmenu">4.2 Main menu bar</a></h3> |
| 584 |
|
| 585 |
<p> |
| 586 |
As already mentioned before in this manual, the GUI has a Main menu bar at the |
| 587 |
top of the openMSX main window. The menu bar fades out when the MSX screen has |
| 588 |
focus. To get it back, move the mouse cursor to the top of the openMSX window. |
| 589 |
</p> |
| 590 |
|
| 591 |
<p class="image"> |
| 592 |
<img src="main_menu_bar.png" width="588" height="22" alt="Main menu bar."> |
| 593 |
</p> |
| 594 |
<p> |
| 595 |
The Main menu bar contains the following top level menus: |
| 596 |
</p> |
| 597 |
<dl> |
| 598 |
<dt>Machine</dt> |
| 599 |
<dd>Selecting the different machines (computer models)</dd> |
| 600 |
<dd>Saving and loading of setups, i.e. machines including whatever the user put into it.</dd> |
| 601 |
<dd>Triggering machine reset and enable or disable power</dd> |
| 602 |
<dt>Media</dt> |
| 603 |
<dd>Inserting and removing media: ROM or extension cartridges, disks, cassette |
| 604 |
tapes, laserdiscs, ...</dd> |
| 605 |
<dt>Connectors</dt> |
| 606 |
<dd>Controlling which devices are plugged into which connectors: |
| 607 |
printers, joysticks, mice, dongles, MIDI equipment, ...</dd> |
| 608 |
<dt>Save state</dt> |
| 609 |
<dd>All save state and replay related functionality, plus some related settings.</dd> |
| 610 |
<dt>Tools</dt> |
| 611 |
<dd>Several tools that can make your life easier, like virtual keyboard, |
| 612 |
copying and pasting, audio and video capture, disk manipulation/management, |
| 613 |
trainers and cheats, audio chip tools and gadgets, etc..</dd> |
| 614 |
<dt>Settings</dt> |
| 615 |
<dd>A collection of the most important settings for Video, Sound, |
| 616 |
Speed, Input, the GUI and Misc settings.</dd> |
| 617 |
<dd>An uncategorized alphabetical list with all available settings.</dd> |
| 618 |
<dt>Debugger</dt> |
| 619 |
<dd>A set of powerful debugging tools for the developer. Practically all |
| 620 |
functionality from the old, standalone openMSX debugger has been included.</dd> |
| 621 |
<dt>Help</dt> |
| 622 |
<dd>Links to get (more) help on using openMSX.</dd> |
| 623 |
</dl> |
| 624 |
|
| 625 |
<p> |
| 626 |
If you like, you can even undock the main menu bar from the main openMSX |
| 627 |
window. This is especially useful if you want to stream the openMSX main |
| 628 |
window, without showing your interaction with the openMSX menus. |
| 629 |
Use the triangular icon on the left in the Main menu bar to undock or redock |
| 630 |
it. |
| 631 |
</p> |
| 632 |
|
| 633 |
<h3><a id="guiother">4.3 Other default GUI elements</a></h3> |
| 634 |
|
| 635 |
<p> |
| 636 |
Besides the Main menu bar, some other main GUI elements you are likely to see. |
| 637 |
Here is a small overview. |
| 638 |
</p> |
| 639 |
|
| 640 |
<dl> |
| 641 |
<dt>Reverse bar</dt> |
| 642 |
<dd><img src="reverse_bar.png" width="245" height="39" alt="Main menu bar."></dd> |
| 643 |
<dd>Placed on the lower right of the main openMSX window by default.</dd> |
| 644 |
<dd>Fades out when the mouse cursor is not on top of it, by default. So it's often not visible.</dd> |
| 645 |
<dd>Select <span class="menu-reference">Right click → Allow |
| 646 |
move</span> and/or (un)select <span class="menu-reference">Right click → |
| 647 |
Hide title</span> to move and resize it, possibly outside the main openMSX |
| 648 |
window.</dd> |
| 649 |
<dd>Can be disabled via <span class="menu-reference">Main menu bar → Save |
| 650 |
state → Reverse/replay settings → Show reverse bar</span>.</dd> |
| 651 |
<dd>Blue means it's replaying (with interruption possible), red means it's recording new input and green means it's replaying without interruption possible.</dd> |
| 652 |
<dt>OSD icons</dt> |
| 653 |
<dd><img src="osd_icons.png" width="516" height="57" alt="Main menu bar."></dd> |
| 654 |
<dd>Represent the LEDs on the machines and contain important status icons.</dd> |
| 655 |
<dd>Appear in the lower left corner by default.</dd> |
| 656 |
<dd>Most icons fade out by default (so typically nothing would be visible).</dd> |
| 657 |
<dd>Can be configured via <span class="menu-reference">Main menu bar → |
| 658 |
Settings → Misc → Configure OSD icons</span>.</dd> |
| 659 |
<dd>Similar to the reverse bar: (un)select "Hide title" and/or "Allow move", |
| 660 |
and drag the icons to a new location, possibly outside the main openMSX window, |
| 661 |
possibly docked to another window.</dd> |
| 662 |
<dt>Status bar</dt> |
| 663 |
<dd><img src="status_bar.png" width="739" height="29" alt="Main menu bar."></dd> |
| 664 |
<dd>Shows up at the bottom of the main openMSX window and contains some |
| 665 |
information about the currently running machine and emulation performance.</dd> |
| 666 |
<dd>Disabled by default, can be enabled via <span class="menu-reference">Main |
| 667 |
menu bar → Settings → Misc → Show status bar</span>.</dd> |
| 668 |
</dl> |
| 669 |
|
| 670 |
<h3><a id="guiadvanced">4.4 Advanced topics</a></h3> |
| 671 |
|
| 672 |
<p> |
| 673 |
The GUI allows you to put any window inside the main openMSX window, or outside |
| 674 |
of it. But windows can also be docked together, at the (left/right/top/bottom) |
| 675 |
edge of any window except the main window, even in a tab bar. |
| 676 |
</p> |
| 677 |
|
| 678 |
<p> |
| 679 |
The GUI also has specific settings, like shortcuts that can be used in the GUI only. |
| 680 |
</p> |
| 681 |
|
| 682 |
<p> |
| 683 |
Also, you can save and load layouts of windows that are combined with each |
| 684 |
other. This is still a rather rough feature, as it also saves and loads other |
| 685 |
data, like the history information from some menus. |
| 686 |
</p> |
| 687 |
|
| 688 |
<p> |
| 689 |
As an example of a layout, we created one with a debugger focus. The image below shows: |
| 690 |
</p> |
| 691 |
<ul> |
| 692 |
<li>docking with split windows horizontal/vertical, sometimes multiple times</li> |
| 693 |
<li>docking with tab bar (e.g. memory/VRAM/PSG regs),</li> |
| 694 |
<li>hiding the (sub)window title, as it is often quite obvious. For "stack" this wasn't done on purpose, to show the difference.</li> |
| 695 |
</ul> |
| 696 |
|
| 697 |
<p class="image"> |
| 698 |
<img src="debugger-layout.png" width="935" height="610" alt="Example debugger focused layout."> |
| 699 |
</p> |
| 700 |
|
| 701 |
<h3><a id="guiadvanced_tips">4.4.1 Some tips and tricks</a></h3> |
| 702 |
|
| 703 |
<p> |
| 704 |
Docking windows can be done in two main ways. Both start by dragging a window |
| 705 |
over another one. If you do that a popup will appear with 5 sections (middle, |
| 706 |
east, west, north, south). |
| 707 |
</p> |
| 708 |
<ul> |
| 709 |
<li>If you drop the window in the middle, then you dock both windows into a tab-bar. This is useful if you don't need to see both windows at once (and when both have approx the same size). As an alternative you can also drag two title bars onto each other.</li> |
| 710 |
<li>If you drop on one of the 4 directions, the window will split in two (horizontally/vertically) and the two windows are shown next to each other. (The two sections can be resized via dragging the divider line).</li> |
| 711 |
</ul> |
| 712 |
<p> |
| 713 |
In both cases the windows are now grouped, they will move together and minimize together. |
| 714 |
</p> |
| 715 |
|
| 716 |
<p> |
| 717 |
The debugger features can require a lot of screen space. Showing everything at |
| 718 |
once won't be possible (unless maybe if you have a 4K monitor). To accomodate |
| 719 |
for this, we do try to pay attention to making all openMSX windows compact. |
| 720 |
</p> |
| 721 |
<p> |
| 722 |
Here are some tips focused on that:</p> |
| 723 |
<ul> |
| 724 |
<li>Create groups of windows (via docking) that you always use together. Then you can minimize/restore such groups.</li> |
| 725 |
<li>You'll soon be familiar with the different debug windows, and then a title like "CPU flags" isn't very useful anymore. You can hide the title via the window menu (the downwards triangle in the top-left corner of a (docked) window). This does save some space.</li> |
| 726 |
<li>Use tab-bars for windows that you don't (often) need together. For example (depending on your use case) you may not need the console together with the memory view, then dock these two in a tab-bar instead of next to each other. Similar for the bitmap and tile viewer, you'll not often need these together, Or just close those windows you don't currently/often need.</li> |
| 727 |
<li>Some (sub)windows have a configurable layout. E.g. right click in the "CPU flags" window, then in the context window choose between horizontal/vertical layout. Depending on how you arrange your other windows, one of these two layouts may fit better. Or hide the undocumented XY flags, you don't often need these.</li> |
| 728 |
<li>In many tables you can hide columns that you don't (currently) need. For example in the "Disassembly" window right-click on the table header, then you can e.g. hide the "opcode" column to save some space. (In most tables you can also drag the columns into a different order). On the other hand, some columns are hidden by default, like the "Action" and "Once" column in the "Breakpoints" window, unhide these if you need them.</li> |
| 729 |
<li>Some windows have collapsible sections. For example the "Tile viewer", once you've chosen the correct settings, you can collapse the "Settings" section to make more room for the "Pattern Table" and "Name Table" sections. And maybe you don't always need to see both these tables? Same for the "Sprite viewer", "VDP register", etc.</li> |
| 730 |
</ul> |
| 731 |
|
| 732 |
Tips if you stil end up to have many (overlapping) windows: |
| 733 |
<ul> |
| 734 |
<li>You can sometimes more easily navigate between them via CTRL-TAB. This also works for docked windows. And you can also use this to bring window to the front.</li> |
| 735 |
<li>If you want to move them around without accidentally docking them, then grab the window on some empty region (rather than the title bar) to move them.</li> |
| 736 |
</ul> |
| 737 |
|
| 738 |
|
| 739 |
|
| 740 |
|
| 741 |
|
| 742 |
|
| 743 |
<h2><a id="media">5. Running MSX Software and Using Media</a></h2> |
| 744 |
|
| 745 |
<p> |
| 746 |
With this information, you can run most of the existing MSX software. If you |
| 747 |
use the GUI, refer to the <span class="menu-reference">Main menu bar → |
| 748 |
Media</span> menu. |
| 749 |
</p> |
| 750 |
|
| 751 |
<p> |
| 752 |
For all supported media files, there is a list of filename extensions that are |
| 753 |
recognized by openMSX. If you run openMSX from the command line, adding a file |
| 754 |
name (with path if necessary) as a command-line option, openMSX will insert the |
| 755 |
file as the proper type of media. The list of supported extensions for each |
| 756 |
media type can be easily retrieved with <code>-h</code> option on the command |
| 757 |
line. For some media, examples of command-line usage are given below. |
| 758 |
</p> |
| 759 |
|
| 760 |
<p> |
| 761 |
If you drag and drop a file with one of these supported extensions |
| 762 |
into the main openMSX window, openMSX will try to handle it accordingly. |
| 763 |
</p> |
| 764 |
|
| 765 |
<h3><a id="roms">5.1 Running ROM software</a></h3> |
| 766 |
|
| 767 |
<p> |
| 768 |
In the GUI you can choose which ROM software you want to run by selecting a |
| 769 |
Cartridge Slot from the <span |
| 770 |
class="menu-reference">Main menu bar → Media</span> menu. This will open a |
| 771 |
window where you can tell openMSX exactly what you want to put in the slot, |
| 772 |
like a ROM image, which mapper to use if the automatically selected one isn't |
| 773 |
correct, and whether the MSX should be reset after inserting. |
| 774 |
</p> |
| 775 |
<p> |
| 776 |
And finally, you can |
| 777 |
also browse for and select (multiple) IPS patches to apply to the selected ROM |
| 778 |
image. IPS patches are files that describe a modification of the ROM you are |
| 779 |
applying it to, e.g. a translation or a cheat. This way you do not need to |
| 780 |
alter the original files. |
| 781 |
</p> |
| 782 |
|
| 783 |
<h4>Command line and console</h4> |
| 784 |
|
| 785 |
<p> |
| 786 |
Using the command line, suppose you want to run the ROM file |
| 787 |
<code>galious.rom</code>. Then you simply type: |
| 788 |
</p> |
| 789 |
<div class="commandline">openmsx galious.rom</div> |
| 790 |
<p> |
| 791 |
and the emulated MSX will run the game. (Of course, |
| 792 |
in this case, the file <code>galious.rom</code> should be in the current directory. |
| 793 |
You can also explicitly indicate that the thing is a ROM image like this: |
| 794 |
</p> |
| 795 |
<div class="commandline">openmsx -cart galious.gam</div> |
| 796 |
<p> |
| 797 |
This lets openMSX know that the file <code>galious.gam</code> is a ROM |
| 798 |
cartridge and that openMSX should insert it in the first available free |
| 799 |
cartridge slot. You can also use <code>-carta</code> to explicitly specify |
| 800 |
cartridge slot A. |
| 801 |
</p> |
| 802 |
<p> |
| 803 |
You can also explicitly specify the mapper type to use (<code>Konami</code> |
| 804 |
for instance) with the <code>-romtype</code> option like this: |
| 805 |
</p> |
| 806 |
<div class="commandline">openmsx galious.rom -romtype Konami</div> |
| 807 |
<p> |
| 808 |
Note that in practice you won't need this, because almost all known ROM images |
| 809 |
are in the database. Obviously, for newly developed ROMs this won't be the case |
| 810 |
and openMSX will then apply a heuristic to guess the correct type as a |
| 811 |
fallback if the option is not specified. This doesn't always work correctly, |
| 812 |
especially for uncommon mapper types, and then it will select the wrong type |
| 813 |
and the program will not work. So, that is a typical case where to |
| 814 |
use this option. Make sure that it follows the ROM it applies to immediately |
| 815 |
on the command line. |
| 816 |
</p> |
| 817 |
|
| 818 |
<p> |
| 819 |
To apply an IPS patch using the command line, provide the IPS |
| 820 |
filename like this: |
| 821 |
</p> |
| 822 |
<div class="commandline">openmsx -cart galious.rom -ips galiouspatch.ips</div> |
| 823 |
<p> |
| 824 |
As with the <code>-romtype</code> option, the <code>-ips</code> option on the |
| 825 |
command line must follow the ROM file it applies to directly. You can also use |
| 826 |
multiple <code>-ips</code> options if you want to apply multiple patches. |
| 827 |
</p> |
| 828 |
|
| 829 |
<p> |
| 830 |
If you already have openMSX running and want to insert cartridges at runtime |
| 831 |
(maybe even when the MSX is powered on), you can use the <code><a |
| 832 |
class="external" href="commands.html#cart">carta</a></code> command in the <a |
| 833 |
class="internal" href="#console">console</a> as well, which is just as |
| 834 |
powerful. |
| 835 |
</p> |
| 836 |
|
| 837 |
<h3><a id="disks">5.2 Running Disk Software</a></h3> |
| 838 |
|
| 839 |
<h4><a id="diskimages">5.2.1 Using Disk Images</a></h4> |
| 840 |
|
| 841 |
<p> |
| 842 |
Of course, this can only be done if the running machine has one or more disk |
| 843 |
drives. From the GUI, simply select the Disk Drive you want to change the disk |
| 844 |
image for. This will open a Disk Drive window where you can specify what must |
| 845 |
be in the drive: a disk image (select a disk image file, or create a new disk |
| 846 |
image), a directory to be used as disk (see next section), a RAM disk |
| 847 |
(temporary disk image in RAM), or nothing at all. As with ROM images, |
| 848 |
IPS patches can be selected to be applied. |
| 849 |
</p> |
| 850 |
|
| 851 |
<p> |
| 852 |
Disk images in compressed format ((g)zip, xsa) can be used as regular disk images, |
| 853 |
but do note that they are read-only. |
| 854 |
Note that in zipped disk images, the first file that is packed into the zip file |
| 855 |
will be used as disk image. |
| 856 |
</p> |
| 857 |
|
| 858 |
|
| 859 |
<h5>Command line and console</h5> |
| 860 |
|
| 861 |
<p> |
| 862 |
To specify disk images on the command line, you can type: |
| 863 |
</p> |
| 864 |
<div class="commandline">openmsx relax.dsk</div> |
| 865 |
<p> |
| 866 |
for example. Or, if you use a disk image with a filename extension that is |
| 867 |
unknown to openMSX: |
| 868 |
</p> |
| 869 |
<div class="commandline">openmsx -diska relax.di</div> |
| 870 |
|
| 871 |
<p> |
| 872 |
You can also change disks at run-time of course. Just type |
| 873 |
</p> |
| 874 |
<div class="commandline"> |
| 875 |
<a class="external" href="commands.html#disk">diska</a> <diskimage> |
| 876 |
</div> |
| 877 |
<p> |
| 878 |
in the <a class="internal" href="#console">console</a> to put the specified |
| 879 |
disk image in drive A. To eject the disk from drive A, use: |
| 880 |
</p> |
| 881 |
<div class="commandline"> |
| 882 |
<a class="external" href="commands.html#disk">diska</a> eject |
| 883 |
</div> |
| 884 |
<p> |
| 885 |
Note that inserting another disk image automatically ejects the previous one. |
| 886 |
</p> |
| 887 |
|
| 888 |
<p> |
| 889 |
To apply an IPS patch, provide the IPS filename like this: |
| 890 |
</p> |
| 891 |
<div class="commandline">openmsx SDSNAT1C.DSK -ips sdsnat1-eng.ips</div> |
| 892 |
<p> |
| 893 |
On the command line, the <code>-ips</code> option must immediately follow the disk image |
| 894 |
it applies to. You can also use multiple <code>-ips</code> options if you |
| 895 |
want to apply multiple patches. |
| 896 |
</p> |
| 897 |
|
| 898 |
<p> |
| 899 |
You can also apply the patches when changing disks at run-time in the console. |
| 900 |
Just type something like |
| 901 |
</p> |
| 902 |
<div class="commandline"> |
| 903 |
<a class="external" href="commands.html#disk">diska</a> SDSNAT1C.DSK.gz |
| 904 |
sdsnat1-eng.ips sd-cheat.ips |
| 905 |
</div> |
| 906 |
<p> |
| 907 |
in the console to put the specified gzipped disk image SDSNAT1C.DSK.gz in drive |
| 908 |
A, with both IPS patches applied. |
| 909 |
</p> |
| 910 |
|
| 911 |
<h4><a id="dirasdisk">5.2.2 Using Directories as Disks</a></h4> |
| 912 |
|
| 913 |
<p> |
| 914 |
The DirAsDsk feature permits you to use a directory on your host computer's |
| 915 |
file system as a disk image for your emulated MSX. Note that this has nothing |
| 916 |
to do with harddisk emulation. It simply creates a |
| 917 |
virtual disk structure in memory from the files that are in the directory |
| 918 |
that you specified as if it were a disk image. So, on the command line: </p> |
| 919 |
<div class="commandline"> |
| 920 |
openmsx -diska . |
| 921 |
</div> |
| 922 |
<p> |
| 923 |
will try to put all files of the current directory on a disk image in memory and |
| 924 |
start openMSX with it. The actual data is still read from/written to the files |
| 925 |
in your directory so that if you change the contents of the files, these changes |
| 926 |
are immediately visible in the emulated MSX. This way you can for instance |
| 927 |
edit source files with your favourite text editor but compile them immediately in |
| 928 |
the emulated MSX. |
| 929 |
</p> |
| 930 |
<p> |
| 931 |
Using the default value of the setting <a class="external" |
| 932 |
href="commands.html#DirAsDSKmode">DirAsDSKmode</a> (full), all changes to the |
| 933 |
directory on the host system <em>and</em> on the MSX system are performed, so |
| 934 |
that they are immediately visible to the other side. If this is not the desired |
| 935 |
behaviour, please <a class="external" href="commands.html#DirAsDSKmode">check |
| 936 |
the documentation</a> of that setting. |
| 937 |
</p> |
| 938 |
<p> |
| 939 |
<em>Be careful when writing to files from your emulated MSX.</em> In the |
| 940 |
default 'full' mode, you can change/overwrite/delete/corrupt files on your host |
| 941 |
system, if you made them accessible for the emulated MSX! Still, this is the |
| 942 |
behaviour what most people want/expect and it's very useful if you know what |
| 943 |
you are doing. |
| 944 |
</p> |
| 945 |
<p> |
| 946 |
Note that MSX disks only have a limited capacity, typically 720kB. If the |
| 947 |
host directory contains more data, then some host files will be ignored and |
| 948 |
they will not appear in the virtual disk image. |
| 949 |
</p> |
| 950 |
|
| 951 |
<h4><a id="realdisks">5.2.3 Using Real Disks</a></h4> |
| 952 |
|
| 953 |
<p> |
| 954 |
We do not recommend using real disks (e.g. with a USB floppy drive) |
| 955 |
with openMSX. There is no specific support for this. |
| 956 |
</p> |
| 957 |
|
| 958 |
<h4><a id="diskmanagement">5.2.4 Managing Disk Images</a></h4> |
| 959 |
|
| 960 |
<p> |
| 961 |
openMSX has a special command to perform file imports and |
| 962 |
exports, with support for normal disk images, Sunrise IDE harddisk images with partitions (FAT12 |
| 963 |
only), and Nextor harddisk images with partitions (FAT12 and FAT16). |
| 964 |
<p> |
| 965 |
<p> |
| 966 |
In the GUI, you can find this tool under <span class="menu-reference">Main menu |
| 967 |
bar → Tools → Disk Manipulator</span>. This will open a big window, |
| 968 |
which has many powerful options. On the left side you select the emulated |
| 969 |
machine drive (any existing drive, or the "Virtual drive" which only exists in |
| 970 |
memory). On the right side, you see the host directories with their file |
| 971 |
content. Use the arrows in the middle to transfer files, the plus button on the |
| 972 |
left side to create a new (hard) disk image and the directory button to browse |
| 973 |
for a disk image to insert. |
| 974 |
</p> |
| 975 |
|
| 976 |
<p> |
| 977 |
For the console commands that are behind this window, please see the separate manual called |
| 978 |
<a class="external" href="diskmanipulator.html">Using diskmanipulator</a>. |
| 979 |
</p> |
| 980 |
|
| 981 |
<h3><a id="tape">5.3 Running Tape Software</a></h3> |
| 982 |
|
| 983 |
<p> |
| 984 |
First thing you need to be aware of: this can only be done on machines that |
| 985 |
have a cassette port. Most do, but the MSX turboR machines do not, so tape |
| 986 |
software cannot be used on these machines. |
| 987 |
</p> |
| 988 |
|
| 989 |
<p> |
| 990 |
Cassette/tape image file formats that are supported are WAV files (raw digitized |
| 991 |
recordings of real tapes) and CAS/TSX files. Differences are explained below. |
| 992 |
</p> |
| 993 |
|
| 994 |
<p> |
| 995 |
In the GUI select <span class="menu-reference">Main menu bar → Media → Tape |
| 996 |
Deck</span> to open the virtual cassette player control window, which allows |
| 997 |
you to insert a cassette tape image. |
| 998 |
</p> |
| 999 |
|
| 1000 |
<p>To insert a tape image from the <a class="internal" href="#console">console</a>, type: |
| 1001 |
</p> |
| 1002 |
<div class="commandline"> |
| 1003 |
<a class="external" href="commands.html#cassetteplayer">cassetteplayer</a> insert <file>.wav |
| 1004 |
</div> |
| 1005 |
<p> |
| 1006 |
Once inserted, in MSX Basic, type: |
| 1007 |
</p> |
| 1008 |
<div class="commandline"> |
| 1009 |
run"cas:" |
| 1010 |
</div> |
| 1011 |
<p> |
| 1012 |
(or another command to load the program on 'tape'.) |
| 1013 |
</p> |
| 1014 |
|
| 1015 |
<p> |
| 1016 |
The cassetteplayer related commands/settings that are controlled in the tape deck window are: |
| 1017 |
</p> |
| 1018 |
<ul> |
| 1019 |
<li><code>cassetteplayer rewind</code>, to rewind the tape</li> |
| 1020 |
<li><code>cassetteplayer eject</code>, to eject the tape</li> |
| 1021 |
<li><code>cassetteplayer new <filename></code>, to create a new WAV cassette image to record to; also sets the cassette player in record mode</li> |
| 1022 |
<li><code>cassetteplayer play</code>, to set the cassette player in play mode (when you've just recorded to the cassette)</li> |
| 1023 |
<li><code>cassetteplayer record</code>, to set the cassette player in record mode, to append to existing cassette images (NOT IMPLEMENTED YET)</li> |
| 1024 |
<li><code>set cassetteplayer_volume</code>, to set the volume of the cassette player sound (yeah, the screeching tape sounds!)</li> |
| 1025 |
</ul> |
| 1026 |
|
| 1027 |
<p> |
| 1028 |
As you can see in this list, appending to existing cassette images (or |
| 1029 |
(partially) overwriting them) is not supported (yet). If you want to save |
| 1030 |
again, just insert a blank tape by using the <code>cassetteplayer new</code> |
| 1031 |
command again (or the Record button with the circle icon in the Tape Deck |
| 1032 |
window). |
| 1033 |
</p> |
| 1034 |
|
| 1035 |
<h4><a id="cas">5.3.1 Using CAS and TSX files</a></h4> |
| 1036 |
<p> |
| 1037 |
You can also use the so-called CAS files and also TSX files. Use them exactly as you would use WAV |
| 1038 |
files, described in the previous section. |
| 1039 |
</p> |
| 1040 |
|
| 1041 |
<p> |
| 1042 |
We don't support using CAS files by patching a BIOS natively, because it is not |
| 1043 |
really something we want: we prefer a more authentic emulation without hacks |
| 1044 |
like this. |
| 1045 |
So, the CAS (and also TSX) files are automatically converted to WAV files, internally. Note |
| 1046 |
that the loading time is drastically longer this way (but the <span class="menu-reference">Main menu bar → Settings → Speed → Go full speed when loading</span> <a class="external" href="commands.html#fullspeedwhenloading">setting</a> |
| 1047 |
will help a lot). On the other hand, you will be able to hear the cassette |
| 1048 |
sounds also with these file formats... Admit it, using cassettes with an MSX |
| 1049 |
without those characteristic sounds just wouldn't be the same. |
| 1050 |
</p> |
| 1051 |
|
| 1052 |
<p> |
| 1053 |
To make it even more comfortable to run software from cassette tapes, check the <span class="menu-reference">Main menu bar → Media → Tape Deck → Controls → (try to) Auto Run</span> <a class="external" href="commands.html#autoruncassettes">setting</a>, that will attempt to |
| 1054 |
type the loading instruction for you after the MSX has started up. |
| 1055 |
</p> |
| 1056 |
|
| 1057 |
<p> |
| 1058 |
Note that saving to existing cassette images is not possible; you can |
| 1059 |
only save to new cassette images in WAV format. |
| 1060 |
</p> |
| 1061 |
|
| 1062 |
<h3><a id="harddisks">5.4 Emulating MSX Harddisks and CD-ROM</a></h3> |
| 1063 |
|
| 1064 |
<p> |
| 1065 |
The Sunrise IDE interface was the first one to be emulated in openMSX, so by now it's thoroughly supported. |
| 1066 |
Later support for two types of SCSI interfaces was added: |
| 1067 |
the Gouda/Novaxis SCSI interface and the MEGA-SCSI, followed by support for |
| 1068 |
the MegaFlashROM SCC+ SD, the Carnivore 2, and the Beer IDE interfaces. Not all harddisk management tools may support these newer mass storage devices. |
| 1069 |
</p> |
| 1070 |
|
| 1071 |
<p> |
| 1072 |
The extensions that enable this have a built-in mass storage (harddisk, SD card, etc.) configuration, in the |
| 1073 |
form of a 100MB disk image. This is the default size: if the harddisk |
| 1074 |
image is not present, a file is created with this size. The image will end up |
| 1075 |
in your openMSX user |
| 1076 |
directory<code>/persistent/NAME/untitled1/IMAGENAME.dsk</code>, where NAME is |
| 1077 |
the name of the extension used and IMAGENAME is a name that is configured in |
| 1078 |
the extension's XML file (e.g. default <code>hd.dsk</code> for the Sunrise IDE). |
| 1079 |
</p> |
| 1080 |
|
| 1081 |
<p> |
| 1082 |
When using these extensions for the first time, you have to treat them as if |
| 1083 |
they were real interfaces with a blank harddisk connected. How they should be initialised |
| 1084 |
depends on the type. We advise you read the manuals, the sections |
| 1085 |
below give some hints. The <code><a class="external" |
| 1086 |
href="diskmanipulator.html">diskmanipulator</a></code> may be helpful, as it |
| 1087 |
supports harddisk images with both Sunrise IDE and Nextor compatible partition |
| 1088 |
table formats. |
| 1089 |
</p> |
| 1090 |
|
| 1091 |
<p> |
| 1092 |
For clarity's sake: since the emulation is done on a big disk image, data corruption of your PC's harddisk is impossible. You will need free |
| 1093 |
disk space for this image, however (default size: 100MB). In other words, you cannot use a normal PC harddisk as an MSX harddisk for these extensions. |
| 1094 |
</p> |
| 1095 |
|
| 1096 |
<p> |
| 1097 |
The way to use files from your real PC harddisk on an emulated MSX, |
| 1098 |
is by using the DirAsDsk feature. See the <a class="internal" |
| 1099 |
href="#dirasdisk">DirAsDsk section</a> for more details. |
| 1100 |
</p> |
| 1101 |
|
| 1102 |
<p> |
| 1103 |
In the GUI under <span class="menu-reference">Main menu bar → Media</span> |
| 1104 |
you can find entries like "Hard Disk A" or "CDROM Drive |
| 1105 |
A" if such devices are connected to the (IDE/SCSI/SD) extension in your |
| 1106 |
currently active machine. If wanted, you can also change the used image, |
| 1107 |
but note that media like harddisks require the machine |
| 1108 |
to be powered off first (see the <span class="menu-reference">Main menu |
| 1109 |
bar → Machine</span> menu for the <code><a class="external" href="commands.html#power">power</a></code> |
| 1110 |
setting). |
| 1111 |
</p> |
| 1112 |
|
| 1113 |
<p> |
| 1114 |
To specify the harddisk image to be used on the command line, use the applicable command-line option, e.g. for Sunrise IDE: |
| 1115 |
</p> |
| 1116 |
<div class="commandline">openmsx -ext ide -hda symbos.dsk</div> |
| 1117 |
<p> |
| 1118 |
This command gives you the ide extension with symbos.dsk as harddisk |
| 1119 |
image. You can also change the harddisk image at run time in the <a |
| 1120 |
class="internal" href="#console">console</a>, with a command similar to the <code><a class="external" |
| 1121 |
href="commands.html#disk">diska</a></code> command: |
| 1122 |
</p> |
| 1123 |
<div class="commandline"> |
| 1124 |
<a class="external" href="commands.html#hd">hda</a> <diskimage> |
| 1125 |
</div> |
| 1126 |
|
| 1127 |
<p>Please read the following sections for details about the specific extensions.</p> |
| 1128 |
|
| 1129 |
<h4><a id="ide">5.4.1 Sunrise IDE</a></h4> |
| 1130 |
|
| 1131 |
<p> |
| 1132 |
The extension for this is called 'ide' (shown with the full name Sunrise |
| 1133 |
ATA-IDE in the extension selector). By default it has a harddisk connected to |
| 1134 |
the master port and a CD-ROM player connected to the slave port. |
| 1135 |
</p> |
| 1136 |
|
| 1137 |
<p> |
| 1138 |
The 'ide' extension needs the BIOS that can be flashed into the Sunrise IDE |
| 1139 |
interface. It can be downloaded from the <a class="external" |
| 1140 |
href="http://www.msx.ch/sunformsx/download/dl-ide.html">Sunrise for MSX web |
| 1141 |
site</a>. |
| 1142 |
</p> |
| 1143 |
|
| 1144 |
<p> |
| 1145 |
The initialisation of a Sunrise IDE harddisk is described in the text files |
| 1146 |
that come with the FDISK program for IDE, downloadable from the <a |
| 1147 |
class="external" |
| 1148 |
href="http://www.msx.ch/sunformsx/download/dl-ide.html">Sunrise for MSX web |
| 1149 |
site</a>. There are also <a class="external" |
| 1150 |
href="https://www.msx.org/forum/semi-msx-talk/emulation/how-get-sunrise-ide-working-openmsx">some</a> |
| 1151 |
<a class="external" |
| 1152 |
href="https://www.msx.org/forum/semi-msx-talk/emulation/openmsx-harddisk-emulation">threads</a> |
| 1153 |
on the MSX Resource Center forum that may give you valuable hints. |
| 1154 |
</p> |
| 1155 |
<p> |
| 1156 |
You can sidestep these procedures by using the <code><a class="external" |
| 1157 |
href="diskmanipulator.html">diskmanipulator</a></code> to create an initial hd |
| 1158 |
image complete with any desired files and subdirectories. For |
| 1159 |
instance to create a harddisk with 3 partitions of 32 megabyte on it, and have |
| 1160 |
each partition filled with files and subdirectories, proceed as follows: |
| 1161 |
</p> |
| 1162 |
<p> |
| 1163 |
Start openMSX with the ide extension, then type in the <a class="internal" href="#console">console</a>: |
| 1164 |
</p> |
| 1165 |
<div class="commandline"> |
| 1166 |
set <a class="external" href="commands.html#power">power</a> off<br/> |
| 1167 |
<a class="external" href="diskmanipulator.html">diskmanipulator</a> <a class="external" href="diskmanipulator.html#create">create</a> /tmp/new-hd.dsk 32M 32M 32M<br/> |
| 1168 |
<a class="external" href="commands.html#hd">hda</a> /tmp/new-hd.dsk<br/> |
| 1169 |
<a class="external" href="diskmanipulator.html">diskmanipulator</a> <a class="external" href="diskmanipulator.html#import">import</a> hda1 /home/david/msxdostools/<br/> |
| 1170 |
<a class="external" href="diskmanipulator.html">diskmanipulator</a> <a class="external" href="diskmanipulator.html#import">import</a> hda2 /home/david/msxdemos/<br/> |
| 1171 |
<a class="external" href="diskmanipulator.html">diskmanipulator</a> <a class="external" href="diskmanipulator.html#import">import</a> hda3 /home/david/msxdrawings/<br/> |
| 1172 |
set <a class="external" href="commands.html#power">power</a> on |
| 1173 |
</div> |
| 1174 |
|
| 1175 |
<p> |
| 1176 |
As announced above, there is (limited) support for CD-ROM with the 'ide' |
| 1177 |
extension. You can insert an ISO image in that virtual CD-ROM player with the |
| 1178 |
<code>-cda</code> command-line option and change it at run time with the |
| 1179 |
<code><a class="external" href="commands.html#cd">cda</a></code> console |
| 1180 |
command, all similar to the aforementioned <code><a class="external" |
| 1181 |
href="commands.html#hd">hda</a></code> and <code><a class="external" |
| 1182 |
href="commands.html#disk">diska</a></code> commands and options. |
| 1183 |
</p> |
| 1184 |
|
| 1185 |
<h4><a id="beeride">5.4.2 Beer IDE</a></h4> |
| 1186 |
|
| 1187 |
<p> |
| 1188 |
The Beer IDE interface, as brought to us by SOLID, is emulated by openMSX, too. |
| 1189 |
This interface only offers a single device (no master and slave) and can only |
| 1190 |
handle up to 4 (version 1.9) or 5 (version 1.8) partitions of 32MB. On the |
| 1191 |
upside, it doesn't need MSX-DOS2, and thus it can run on any MSX (with |
| 1192 |
64kB RAM to run MSX-DOS). Emulation of this interface should be considered |
| 1193 |
experimental. |
| 1194 |
</p> |
| 1195 |
|
| 1196 |
<p> |
| 1197 |
Usage is identical to using the Sunrise harddisk interface: you can use the |
| 1198 |
GUI, the <a class="external" href="commands.html#hd">hda</a> command and the |
| 1199 |
matching command-line parameter <code>-hda</code> to control which image will |
| 1200 |
be used. |
| 1201 |
</p> |
| 1202 |
|
| 1203 |
<p> |
| 1204 |
By default, the image is 128MB, so that it can fit 4 partitions of 32MB. Firmware |
| 1205 |
version 1.9RC1 is selected by default, because we could not get the 1.8 |
| 1206 |
firmware to work: the MSXFDISK program didn't create partitions which actually |
| 1207 |
worked with the 1.8 firmware. If you want to experiment with it, you can change |
| 1208 |
the firmware to use by editing the extension file in |
| 1209 |
<code>share/extensions/Beer_IDE.xml</code>. |
| 1210 |
</p> |
| 1211 |
|
| 1212 |
<p> |
| 1213 |
With the 1.9RC1 firmware, you can use <code><a class="external" |
| 1214 |
href="diskmanipulator.html">diskmanipulator</a></code> to create a harddisk |
| 1215 |
image and import from and export to them. To get started, partition the default |
| 1216 |
drive with <code>diskmanipulator partition hda -dos1 32M 32M 32M 32M</code>. |
| 1217 |
Then import MSX-DOS system files onto the first partition using |
| 1218 |
<code>diskmanipulator import hda1 <host-path></code>, and now you should |
| 1219 |
be able to boot into MSX-DOS. |
| 1220 |
</p> |
| 1221 |
|
| 1222 |
<p> |
| 1223 |
Unfortunately, the Beer IDE is hardly documented and the software is hard to |
| 1224 |
find. So, it's for experts only! |
| 1225 |
</p> |
| 1226 |
|
| 1227 |
<h4><a id="scsi">5.4.3 SCSI devices</a></h4> |
| 1228 |
|
| 1229 |
<p> |
| 1230 |
First of all: the SCSI emulation is experimental! There is a lot bigger chance |
| 1231 |
that you may lose data on your emulated harddisk images with SCSI than with |
| 1232 |
Sunrise IDE! When we tried it, everything seemed fine, but you have been warned. |
| 1233 |
</p> |
| 1234 |
|
| 1235 |
<p> |
| 1236 |
The SCSI extensions (currently Gouda_SCSI, ESE_MEGA-SCSI and ESE_WAVE-SCSI) |
| 1237 |
have the default 100 MB harddisk image connected on target ID 1 and an (even |
| 1238 |
more experimental) LS-120 device (basically a harddisk like media that can be |
| 1239 |
changed/ejected when the power is on) on target ID 2. |
| 1240 |
</p> |
| 1241 |
|
| 1242 |
<p>Specifying or changing harddisk images works the same as with IDE, see above.</p> |
| 1243 |
|
| 1244 |
<p> |
| 1245 |
To change the disk image of the LS-120 device, use the <code>lsa</code> (LS |
| 1246 |
drive A) command, exactly the same as the <a class="external" |
| 1247 |
href="commands.html#hd">hda</a> command. Of course you do not need to have the |
| 1248 |
power turned off to do this, as this is the whole point of the LS-120 device. |
| 1249 |
You can also just eject it, with the <code>eject</code> subcommand. At the time |
| 1250 |
of writing there seems to be a bug when doing this: the device isn't listed in |
| 1251 |
the device list if there is no media inserted. It is currently not possible to specify an |
| 1252 |
LS-120 device on the command line. |
| 1253 |
</p> |
| 1254 |
|
| 1255 |
<p> |
| 1256 |
Initialisation for the ESE SCSI devices needs tools like <code>MGINST</code>, |
| 1257 |
which can be found on <a class="external" |
| 1258 |
href="http://www.msxnet.org/gtinter/nogame-e.htm">Takamichi's web site</a>. |
| 1259 |
They include small manuals in English. This manual is not the place to explain |
| 1260 |
the procedure, but the idea is as follows. First, install the MSX-DOS 2 kernel |
| 1261 |
in the SRAM of the device, using the <code>MGINST</code> program (you might |
| 1262 |
want to use <code>KSAVER</code> first to save the kernel of your DOS 2 |
| 1263 |
cartridge). After this, the MSX will boot from the SRAM disk. Use the |
| 1264 |
<code>SFORM-1</code> (for MSX-DOS) or the <code>SFORM-2</code> (for MSX-DOS 2) |
| 1265 |
to format the drive (use a physical format, for now). Use <code>ESET</code> to |
| 1266 |
assign drive letters to partitions. |
| 1267 |
</p> |
| 1268 |
|
| 1269 |
<p> |
| 1270 |
For the Gouda (Novaxis) SCSI interface, you need the Novaxis ROM, see also <a |
| 1271 |
class="external" href="http://msx.hansotten.com/index.php?page=msxscsi">Hans |
| 1272 |
Otten's Page</a> or <a class="external" |
| 1273 |
href="http://faq.msxnet.org/scsi.html">The Ultimate MSX FAQ</a>. Those sites |
| 1274 |
also contain manuals for the Novaxis ROM. Initialisation is done with the |
| 1275 |
<code>NFDISK</code> utility, which can be found on <a class="external" |
| 1276 |
href="https://web.archive.org/web/20200315110709/http://members.chello.nl/m.delorme/">Marcel Delorme's site</a> (archived). |
| 1277 |
</p> |
| 1278 |
|
| 1279 |
<h4><a id="sd">5.4.4 MegaFlashROM SCC+ SD</a></h4> |
| 1280 |
|
| 1281 |
<p> |
| 1282 |
Currently there is only one SD interface emulated: the MegaFlashROM SCC+ SD. |
| 1283 |
All features of this cartridge are emulated in the sense that all software currently |
| 1284 |
working with it, runs on openMSX too. It is not emulated accurately |
| 1285 |
enough to rely on it for development. |
| 1286 |
</p> |
| 1287 |
|
| 1288 |
<p> |
| 1289 |
The SD card slots appear in the openMSX user interface as "Hard Disk A/B" and |
| 1290 |
hot plugging is not supported. So, it shows up almost identically to the |
| 1291 |
Sunrise IDE interface. |
| 1292 |
</p> |
| 1293 |
|
| 1294 |
<p> |
| 1295 |
The difference compared to a real MegaFlashROM SCC+ SD, is that the extension does not |
| 1296 |
come with anything flashed on the flash ROM by default. There are two ways to |
| 1297 |
overcome that. The first one is to download the preflashed ROM content (for URL |
| 1298 |
see below) and install it into your systemroms folder, like any usual system |
| 1299 |
ROM. This only works if you use the extension for the first time, unless you |
| 1300 |
manually delete the persistent file for the flash ROM chip (typically in your |
| 1301 |
openMSX user |
| 1302 |
directory<code>/persistent/MegaFlashROM_SCC+_SD/untitled1/megaflashromsccplussd.sram</code>). |
| 1303 |
Only if no such file is found, openMSX will load the content of that ROM file |
| 1304 |
into the flash ROM of the MegaFlashROM SCC+ SD. The second way is manually |
| 1305 |
flashing things like Nextor, the rescue menu and the ROM disk. This is all |
| 1306 |
described in the manual (see at the end of this section) of the MegaFlashROM |
| 1307 |
SCC+ SD, because on a real device you may also need to do this. |
| 1308 |
</p> |
| 1309 |
|
| 1310 |
<p> |
| 1311 |
Once you achieved this, usage is again identical to using the Sunrise harddisk |
| 1312 |
interface, so in the console you can use the <a class="external" |
| 1313 |
href="commands.html#hd">hda/hdb</a> commands and the matching command-line |
| 1314 |
parameters <code>-hda</code> and <code>-hdb</code> to control which image will |
| 1315 |
be used for the first and second SD card. |
| 1316 |
</p> |
| 1317 |
|
| 1318 |
<p> |
| 1319 |
Currently, by default, the first SD card is 8MB and the 2nd SD card is 100MB in |
| 1320 |
size. You can change these defaults by editing the extension file in |
| 1321 |
<code>share/extensions/MegaFlashROM_SCC+_SD.xml</code>. For formatting and |
| 1322 |
managing the SD cards, please refer to its manual and tools on the Flash part |
| 1323 |
of the <a class="external" href="http://www.msxcartridgeshop.com/">MSX |
| 1324 |
Cartridge Shop</a>. It also provides the ROM file with the initial content of |
| 1325 |
the flash ROM as it is shipped on real MegaFlashROM SCC+ SD cartridges. |
| 1326 |
</p> |
| 1327 |
|
| 1328 |
<p> |
| 1329 |
To get files on the SD cards, you can use <code><a class="external" |
| 1330 |
href="diskmanipulator.html">diskmanipulator</a></code> with the |
| 1331 |
<code>-nextor</code> option to partition and to import files, similar to what |
| 1332 |
is explained above <a class="internal" href="#ide">in the Sunrise IDE |
| 1333 |
section</a>. |
| 1334 |
</p> |
| 1335 |
|
| 1336 |
<h3><a id="laserdisc">5.5 Running Laserdisc software</a></h3> |
| 1337 |
|
| 1338 |
<p> |
| 1339 |
In order to run Laserdisc software, you need to have this optional feature |
| 1340 |
compiled into your openMSX binary. Laserdisc is only supported by the Pioneer |
| 1341 |
PX-7 or the Pioneer PX-V60 machines, which have special hardware to control the |
| 1342 |
laserdisc player. |
| 1343 |
</p> |
| 1344 |
|
| 1345 |
|
| 1346 |
<p> |
| 1347 |
The Laserdisc image can be selected under <span class="menu-reference">Main |
| 1348 |
menu bar → Media → LaserDisc Player</span> or in the <a |
| 1349 |
class="internal" href="#console">console</a>, type <code><a class="external" href="commands.html#laserdiscplayer">laserdiscplayer</a> insert <file>.ogv</code> |
| 1350 |
</p> |
| 1351 |
<p> |
| 1352 |
to insert a Laserdisc (image) into the Laserdisc player. |
| 1353 |
By default, the Laserdisc will be loaded automatically. If the |
| 1354 |
<a class="external" href="commands.html#autorunlaserdisc">autorunlaserdisc</a> |
| 1355 |
setting is off, then you will have to take a few steps yourself. |
| 1356 |
</p> |
| 1357 |
|
| 1358 |
<p> |
| 1359 |
After booting the MSX, choose option 1 when asked if you want to run P-BASIC |
| 1360 |
(Palcom-BASIC). In MSX-BASIC, type: |
| 1361 |
</p> |
| 1362 |
|
| 1363 |
<div class="commandline"> |
| 1364 |
call ld |
| 1365 |
</div> |
| 1366 |
<p> |
| 1367 |
to load and run the Laserdisc program. |
| 1368 |
</p> |
| 1369 |
|
| 1370 |
<p> |
| 1371 |
The program is encoded on the right audio channel, which will not be audible. |
| 1372 |
With <code>set <a class="external" |
| 1373 |
href="commands.html#fullspeedwhenloading">fullspeedwhenloading</a> on</code>, |
| 1374 |
openMSX runs at maximum speed whenever the Laserdisc is seeking or loading a |
| 1375 |
program. |
| 1376 |
</p> |
| 1377 |
|
| 1378 |
<h2><a id="input">6. Input Devices</a></h2> |
| 1379 |
|
| 1380 |
<h3><a id="keyboard">6.1 Keyboard</a></h3> |
| 1381 |
|
| 1382 |
<a id="keymapping"></a> |
| 1383 |
<h4><a id="msxkeymapping">6.1.1 MSX Key Mapping</a></h4> |
| 1384 |
|
| 1385 |
<p> |
| 1386 |
The special MSX keys are mapped as follows, the first column for PCs (running |
| 1387 |
Windows, Linux or BSD), the second column for Apple Macintosh computers: |
| 1388 |
</p> |
| 1389 |
|
| 1390 |
<table> |
| 1391 |
<tr> <th>MSX key</th> <th>key (PC)</th> <th>key (Mac)</th> </tr> |
| 1392 |
<tr> <td>CTRL key</td> <td>L-CTRL</td> <td>L-CTRL</td> </tr> |
| 1393 |
<tr> <td><a class="external" href="commands.html#kbd_deadkey1_host_key">dead (accents) key</a></td><td>R-CTRL</td> <td>R-CTRL</td> </tr> |
| 1394 |
<tr> <td>GRAPH key</td> <td>L-ALT</td> <td>L-ALT</td> </tr> |
| 1395 |
<tr> <td><a class="external" href="commands.html#kbd_code_kana_host_key">CODE/KANA key</a></td><td>R-ALT</td> <td>R-ALT</td> </tr> |
| 1396 |
<tr> <td>取消 ('cancel') key</td> <td>L-Windows</td><td></td> </tr> |
| 1397 |
<tr> <td>実行 ('execute') key</td> <td>R-Windows</td><td></td> </tr> |
| 1398 |
<tr> <td>SELECT key</td> <td>F7</td> <td>F7</td> </tr> |
| 1399 |
<tr> <td>STOP key</td> <td>F8</td> <td>F8</td> </tr> |
| 1400 |
<tr> <td>INS key</td> <td>Insert</td> <td>Cmd+I</td> </tr> |
| 1401 |
</table> |
| 1402 |
|
| 1403 |
<h4><a id="cvkeymapping">6.1.2 ColecoVision Key Mapping</a></h4> |
| 1404 |
|
| 1405 |
<p>The ColecoVision controllers are mapped as follows:</p> |
| 1406 |
|
| 1407 |
<table> |
| 1408 |
<tr> <th>direction/key</th> <th>player 1</th> <th>player 2</th> </tr> |
| 1409 |
<tr> <td>up</td> <td>cursor up</td> <td>W</td> </tr> |
| 1410 |
<tr> <td>down</td> <td>cursor down</td> <td>S</td> </tr> |
| 1411 |
<tr> <td>left</td> <td>cursor left</td> <td>A</td> </tr> |
| 1412 |
<tr> <td>right</td> <td>cursor right</td> <td>D</td> </tr> |
| 1413 |
<tr> <td>fire left</td> <td>space, R-CTRL</td> <td>L-CTRL</td> </tr> |
| 1414 |
<tr> <td>fire right</td> <td>L-ALT, R-ALT, R-SHIFT</td> <td>L-SHIFT</td> </tr> |
| 1415 |
<tr> <td>1</td> <td>1, numpad 1</td> <td>R</td> </tr> |
| 1416 |
<tr> <td>2</td> <td>2, numpad 2</td> <td>T</td> </tr> |
| 1417 |
<tr> <td>3</td> <td>3, numpad 3</td> <td>Y</td> </tr> |
| 1418 |
<tr> <td>4</td> <td>4, numpad 4</td> <td>F</td> </tr> |
| 1419 |
<tr> <td>5</td> <td>5, numpad 5</td> <td>G</td> </tr> |
| 1420 |
<tr> <td>6</td> <td>6, numpad 6</td> <td>H</td> </tr> |
| 1421 |
<tr> <td>7</td> <td>7, numpad 7</td> <td>V</td> </tr> |
| 1422 |
<tr> <td>8</td> <td>8, numpad 8</td> <td>B</td> </tr> |
| 1423 |
<tr> <td>9</td> <td>9, numpad 9</td> <td>N</td> </tr> |
| 1424 |
<tr> <td>0</td> <td>0, numpad 0</td> <td>U</td> </tr> |
| 1425 |
<tr> <td>*</td> <td>-, numpad *, numpad -</td> <td>J</td> </tr> |
| 1426 |
<tr> <td>#</td> <td>=, numpad /, numpad +</td> <td>M</td> </tr> |
| 1427 |
</table> |
| 1428 |
|
| 1429 |
<p> |
| 1430 |
Host joysticks can also be used for directions and the fire buttons, but the |
| 1431 |
keys from the telephone-style keypad can only be entered via the host keyboard. |
| 1432 |
</p> |
| 1433 |
|
| 1434 |
<h4><a id="emukeymapping">6.1.3 Emulator Functions Key Mapping</a></h4> |
| 1435 |
|
| 1436 |
<p> |
| 1437 |
The mapping of the keys for emulator functions is fully customisable using the |
| 1438 |
<a class="external" href="commands.html#bind"><code>bind</code></a> command in |
| 1439 |
the <a class="internal" href="#console">console</a>. Your customised key |
| 1440 |
bindings are saved together with the settings. This subsection lists the |
| 1441 |
default key mapping. |
| 1442 |
</p> |
| 1443 |
|
| 1444 |
<table> |
| 1445 |
<tr> <th>keys (PC)</th> <th>keys (Mac)</th> <th>function</th> </tr> |
| 1446 |
<tr> <td>Pause</td> <td>Cmd+P (Pause)</td> <td>Pause emulation</td> </tr> |
| 1447 |
<tr> <td>ALT+F4</td> <td>Cmd+Q (Quit)</td> <td>Quit openMSX</td> </tr> |
| 1448 |
<tr> <td>CTRL+Pause (Break)</td> <td></td> <td>Quit openMSX (not in Windows)</td> </tr> |
| 1449 |
<tr> <td>PrtScr</td> <td>Cmd+D (Dump)</td> <td>Save current screen to a file (<a class="external" href="commands.html#screenshot">screen shot</a>)</td> </tr> |
| 1450 |
<tr> <td>PageUp</td> <td>PageUp</td> <td>Go 1 second back in time, using the <a class="external" href="commands.html#reverse">reverse</a> feature</td> </tr> |
| 1451 |
<tr> <td>PageDown</td> <td>PageDown</td> <td>Go 1 second forward in time, using the <a class="external" href="commands.html#reverse">reverse</a> feature</td> </tr> |
| 1452 |
<tr> <td>F9</td> <td>Cmd+T (Fastforward)</td> <td>Toggle <a class="external" href="commands.html#fastforward">fastforward</a> mode (normal vs fastforward speed)</td> </tr> |
| 1453 |
<tr> <td>F10</td> <td>Cmd+L (consoLe)</td> <td>Toggle <a class="external" href="commands.html#console">console</a> display</td> </tr> |
| 1454 |
<tr> <td>F11 or ALT+Enter</td> <td>Cmd+F (Full)</td> <td>Toggle <a class="external" href="commands.html#fullscreen">full screen</a> mode</td> </tr> |
| 1455 |
<tr> <td>F12</td> <td>Cmd+U (mUte)</td> <td>Toggle <a class="external" href="commands.html#mute">audio mute</a></td> </tr> |
| 1456 |
<tr> <td>ALT+F7</td> <td>Cmd+R (Restore)</td> <td>Quick <a class="external" href="commands.html#savestate">loadstate</a> (from 'quicksave' slot)</td> </tr> |
| 1457 |
<tr> <td>ALT+F8</td> <td>Cmd+S (Save)</td> <td>Quick <a class="external" href="commands.html#savestate">savestate</a> (to 'quicksave' slot)</td> </tr> |
| 1458 |
<tr> <td>CTRL+Win+C</td> <td>Cmd+C (Copy)</td> <td>Copy screen's text content to clipboard</td> </tr> |
| 1459 |
<tr> <td>CTRL+Win+V</td> <td>Cmd+V (paste)</td> <td>Type the text from the clipboard into the MSX</td> </tr> |
| 1460 |
</table> |
| 1461 |
|
| 1462 |
|
| 1463 |
|
| 1464 |
|
| 1465 |
|
| 1466 |
<p> |
| 1467 |
Note that Mac users must use <code>GUI</code> as a modifier for the Command |
| 1468 |
(Apple logo) key. On PC's use <code>GUI</code> for the Windows key. |
| 1469 |
</p> |
| 1470 |
|
| 1471 |
<p> |
| 1472 |
Please note that openMSX is currently intended to be mouse controlled. |
| 1473 |
Some parts of the GUI can also be controlled via keyboard, but this has not |
| 1474 |
been optimized at all for now. Control via gamepad is currently disabled (this |
| 1475 |
might change in a future version). |
| 1476 |
</p> |
| 1477 |
|
| 1478 |
<h4><a id="keyboardlayouts">6.1.4 Keyboard Layouts</a></h4> |
| 1479 |
|
| 1480 |
<p> |
| 1481 |
This section is about how host computer keyboard layouts are mapped to |
| 1482 |
MSX keyboard layouts. This is mostly interesting if those differ |
| 1483 |
(a lot). For example, you have a US-English keyboard on your PC and you are |
| 1484 |
emulating a Japanese MSX computer. Or, you have a Japanese Mac and you are |
| 1485 |
emulating a Spanish MSX computer. |
| 1486 |
</p> |
| 1487 |
|
| 1488 |
<p> |
| 1489 |
There are features to make this as smooth as possible, |
| 1490 |
so that you can use your own keyboard for any kind of MSX with as little |
| 1491 |
surprises as possible. The trick is the new character-based <a class="external" |
| 1492 |
href="commands.html#kbd_mapping_mode">mapping mode</a>, which tries to convert |
| 1493 |
any character you enter with your host computer's keyboard to an MSX key press. |
| 1494 |
For this feature, all MSX hardware configuration files now have information |
| 1495 |
about their keyboard layout. Anyway, this mapping mode is enabled by default, |
| 1496 |
so you don't have to do anything to make this work! |
| 1497 |
</p> |
| 1498 |
|
| 1499 |
<p> |
| 1500 |
However, there are always some pesky details. For those details we refer to the |
| 1501 |
documentation of other keyboard settings, where they are explained in full |
| 1502 |
detail: <a class="external" href="commands.html#kbd_mapping_mode">mapping |
| 1503 |
mode</a> (as mentioned before), <a class="external" |
| 1504 |
href="commands.html#kbd_numkeypad_always_enabled">kbd_numkeypad_always_enabled</a> |
| 1505 |
(use numerical keypad even when your MSX doesn't have one), <a class="external" |
| 1506 |
href="commands.html#kbd_code_kana_host_key">kbd_code_kana_host_key</a> (specify |
| 1507 |
an alternative host key for CODE/KANA) and <a class="external" |
| 1508 |
href="commands.html#kbd_numkeypad_enter_key">kbd_numkeypad_enter_key</a> |
| 1509 |
(specifies mapping of the ENTER key of the keypad). |
| 1510 |
</p> |
| 1511 |
|
| 1512 |
<p> |
| 1513 |
You can find the mapping mode setting in <span class="menu-reference">Main menu |
| 1514 |
bar → Settings → Input → Keyboard mapping mode</span>. |
| 1515 |
</p> |
| 1516 |
|
| 1517 |
<h3><a id="joystick">6.2 Joystick</a></h3> |
| 1518 |
|
| 1519 |
<p> |
| 1520 |
If you have a controller or joystick connected to your PC, you can map its |
| 1521 |
input to one of the emulated MSX joystick (like) devices, internally called <code>msxjoystick1</code>, |
| 1522 |
<code>msxjoystick2</code>, <code>joymega1</code> and <code>joymega2</code>. |
| 1523 |
</p> |
| 1524 |
|
| 1525 |
<p> |
| 1526 |
See the <a class="internal" href="#plug">earlier section about plugging |
| 1527 |
devices</a> on how to connect these devices to your emulated machine. |
| 1528 |
</p> |
| 1529 |
|
| 1530 |
<p> |
| 1531 |
The mapping of your host devices (host controllers, joysticks or keyboard) to |
| 1532 |
these 4 emulated MSX joysticks is fully configurable. The easiest way is to use |
| 1533 |
the GUI menu for that under <span class="menu-reference">Main menu bar → |
| 1534 |
Settings → Input → Configure MSX joysticks</span>. You can also do it |
| 1535 |
in the console with the <a class="external" |
| 1536 |
href="commands.html#msxjoystickN_config">msxjoystick<n>_config/joymega<n>_config</a> |
| 1537 |
settings. |
| 1538 |
</p> |
| 1539 |
|
| 1540 |
<p> |
| 1541 |
Most modern joysticks have more buttons than the 2 buttons that are defined by |
| 1542 |
the MSX standard. Therefore a lot of games use extra keys on the keyboard for |
| 1543 |
extra functionality. For instance, almost all Konami games use F1 to pause |
| 1544 |
the game. You can assign this extra functionality to your joystick by using the |
| 1545 |
<code><a class="external" href="commands.html#bind">bind</a></code> command. As |
| 1546 |
an example here is how to map button 4 of the first joystick to the F1-key, |
| 1547 |
button 5 to F2, ... |
| 1548 |
</p> |
| 1549 |
<div class="commandline"> |
| 1550 |
bind "joy1 button4 down" "keymatrixdown 6 0x20"<br/> |
| 1551 |
bind "joy1 button4 up" "keymatrixup 6 0x20"<br/> |
| 1552 |
bind "joy1 button5 down" "keymatrixdown 6 0x40"<br/> |
| 1553 |
bind "joy1 button5 up" "keymatrixup 6 0x40"<br/> |
| 1554 |
bind "joy1 button6 down" "keymatrixdown 6 0x80"<br/> |
| 1555 |
bind "joy1 button6 up" "keymatrixup 6 0x80"<br/> |
| 1556 |
bind "joy1 button7 down" "keymatrixdown 7 0x01"<br/> |
| 1557 |
bind "joy1 button7 up" "keymatrixup 7 0x01"<br/> |
| 1558 |
bind "joy1 button8 down" "keymatrixdown 7 0x02"<br/> |
| 1559 |
bind "joy1 button8 up" "keymatrixup 7 0x02"<br/> |
| 1560 |
</div> |
| 1561 |
<p> |
| 1562 |
For a more detailed explanation of this command see the <a class="external" |
| 1563 |
href="commands.html#bind">Console Command Reference</a>. Please note that |
| 1564 |
unfortunately, such mappings are not configurable via the GUI menu. |
| 1565 |
</p> |
| 1566 |
<h3><a id="mouse">6.3 Mouse</a></h3> |
| 1567 |
|
| 1568 |
<p> |
| 1569 |
To connect a mouse, you can also use the <span class="menu-reference">Main menu |
| 1570 |
bar → Connectors</span> menu or the <code><a |
| 1571 |
class="external" href="commands.html#plugunplug">plug</a></code> command: <code>plug joyporta mouse</code> |
| 1572 |
will connect a mouse to joystick port A. If you want the joystick emulation |
| 1573 |
feature that some mice (like the Philips SBC-3810 and the Sony MOS-1) have, |
| 1574 |
keep the left mouse key pressed when plugging it in, just as on a real MSX. |
| 1575 |
</p> |
| 1576 |
|
| 1577 |
<p> |
| 1578 |
If you are using openMSX in windowed mode, it might be tricky to use the mouse. |
| 1579 |
The setting: <code>set <a |
| 1580 |
class="external" href="commands.html#grabinput">grabinput</a> on</code> |
| 1581 |
makes sure all input goes to openMSX. Your cursor cannot leave the openMSX |
| 1582 |
window with this setting. Just turn it back to off, if you want to disable this |
| 1583 |
again. If you only want to escape the window briefly, use this command: |
| 1584 |
<code><a class="external" |
| 1585 |
href="commands.html#escape_grab">escape_grab</a></code>. It permits you to |
| 1586 |
leave the window, but the next time you enter it, the cursor is grabbed again. |
| 1587 |
It might be a good idea to bind this command to a key, using the <code><a |
| 1588 |
class="external" href="commands.html#bind">bind</a></code> command, which is |
| 1589 |
mentioned above. You can also toggle the setting via <span |
| 1590 |
class="menu-reference">Main menu bar → Settings → Input → Grab |
| 1591 |
input</span>. |
| 1592 |
</p> |
| 1593 |
|
| 1594 |
<h3><a id="arkanoidpad">6.4 Arkanoid Pad</a></h3> |
| 1595 |
|
| 1596 |
<p> |
| 1597 |
The Arkanoid games by Taito both have support for a special Arkanoid game pad, |
| 1598 |
with a classical rotary knob to control the position of the bat. This device |
| 1599 |
is emulated as well and can be controlled by the mouse. Plug it via the GUI |
| 1600 |
<span class="menu-reference">Main menu bar → Connector</span> menu or in |
| 1601 |
the console with <code><a class="external" href="commands.html#plugunplug">plug</a> joyporta arkanoidpad |
| 1602 |
</code>. |
| 1603 |
</p> |
| 1604 |
|
| 1605 |
<h3><a id="trackball">6.5 Trackball</a></h3> |
| 1606 |
|
| 1607 |
<p> |
| 1608 |
Some MSX trackballs like the HAL CAT and the Sony HB-G7B seem to have identical hardware |
| 1609 |
and are also emulated by openMSX, again using the mouse to control it. In MSX |
| 1610 |
software, the trackball is mostly supported in port B only. Using the console |
| 1611 |
you can use therefore <code><a class="external" |
| 1612 |
href="commands.html#plugunplug">plug</a> joyportb trackball</code>. |
| 1613 |
</p> |
| 1614 |
|
| 1615 |
<p> |
| 1616 |
Quite some HAL programs have support for it, e.g. Hole in One, Eddy II, Music |
| 1617 |
Studio G7, Space Trouble and Super Billiards. The test program provided in the |
| 1618 |
Sony HB-G7B service manual also works fine, of course. |
| 1619 |
</p> |
| 1620 |
|
| 1621 |
<h3><a id="touchpad">6.6 Touchpad</a></h3> |
| 1622 |
|
| 1623 |
<p> |
| 1624 |
Some MSX touch pads like the Philips NMS 1150 Graphic Tablet are also emulated |
| 1625 |
by openMSX, again using the mouse to control it (where mouse button 1 |
| 1626 |
corresponds to touch or no touch and mouse button 2 to the button on the pen of |
| 1627 |
the touch pad). Also the touch pad is mostly supported in port B only, so the |
| 1628 |
console command is <code><a class="external" href="commands.html#plugunplug">plug</a> joyportb touchpad</code> |
| 1629 |
</p> |
| 1630 |
|
| 1631 |
<p> |
| 1632 |
This device is mostly supported by the Philips drawing programs Designer, |
| 1633 |
Designer Plus and Video Graphics (all in port B) and by Pioneer MSX Video Art |
| 1634 |
(port A). |
| 1635 |
</p> |
| 1636 |
|
| 1637 |
<p> |
| 1638 |
Note that the whole openMSX window will function as the surface of the touch |
| 1639 |
pad. This may not align with the actual pixels of the screen in that window, |
| 1640 |
see the <a class="external" |
| 1641 |
href="commands.html#touchpad_transform_matrix">touchpad_transform_matrix</a> |
| 1642 |
setting for how to adjust this. |
| 1643 |
</p> |
| 1644 |
|
| 1645 |
<h3><a id="magickey">6.7 Magic Key</a></h3> |
| 1646 |
|
| 1647 |
<p> |
| 1648 |
Sony made a small dongle for game testers to cheat within the games. The games |
| 1649 |
that have support for it will check if the UP and DOWN keys are pressed. The |
| 1650 |
magic key is supported by these games in port B only (console: <code><a |
| 1651 |
class="external" href="commands.html#plugunplug">plug</a> joyportb |
| 1652 |
magic-key</code>. |
| 1653 |
</p> |
| 1654 |
|
| 1655 |
|
| 1656 |
<p> |
| 1657 |
Known games that can use this Magic Key are: |
| 1658 |
</p> |
| 1659 |
<dl> |
| 1660 |
<dt>Family Boxing (Sony)</dt> |
| 1661 |
<dd>Press the Graph key on the title screen to enter the secret menu</dd> |
| 1662 |
<dt>Jansei (Sony)</dt> |
| 1663 |
<dd>You can set the characteristics of the enemy by moving the cursor to |
| 1664 |
"Actual Battle" on the menu screen and pressing ESC and SELECT.</dd> |
| 1665 |
<dt>Gall Force - Defense of Chaos (Sony)</dt> |
| 1666 |
<dd>A new menu item will appear on the home screen</dd> |
| 1667 |
</dl> |
| 1668 |
|
| 1669 |
<h3><a id="ninjatap">6.8 Ninja Tap</a></h3> |
| 1670 |
|
| 1671 |
<p> |
| 1672 |
The Ninja Tap (忍者タップ) is an adapter designed by Knight's chamber and |
| 1673 |
sold in Japan by PCCM. This adapter allows you to use up to 4 joysticks per port. |
| 1674 |
Plug it via the GUI or with the console using <code><a class="external" |
| 1675 |
href="commands.html#plugunplug">plug</a> joyporta ninjatap</code>. |
| 1676 |
</p> |
| 1677 |
|
| 1678 |
|
| 1679 |
<h3><a id="tetris2dongle">6.9 Tetris II Special Edition dongle</a></h3> |
| 1680 |
|
| 1681 |
<p> |
| 1682 |
Tetris 2 Special Edition from R.A.M., an Italian MSX group, needs the dongle in |
| 1683 |
port B too start the game. So, on the console use <code><a class="external" |
| 1684 |
href="commands.html#plugunplug">plug</a> joyportb tetris2-protection |
| 1685 |
</code> |
| 1686 |
</p> |
| 1687 |
|
| 1688 |
<h3><a id="msxpaddle">6.10 MSX Paddle</a></h3> |
| 1689 |
|
| 1690 |
<p> |
| 1691 |
The MSX paddle controller is a quite simple device, but there are not so many |
| 1692 |
commercial implementations for MSX. The Yamaha MMP-01 is a music pad that is |
| 1693 |
known to use this protocol to transmit its coordinates. Plug it in the console |
| 1694 |
as follows: <code><a class="external" href="commands.html#plugunplug">plug</a> |
| 1695 |
joyporta paddle</code>. |
| 1696 |
</p> |
| 1697 |
|
| 1698 |
<h3><a id="circuitdesignerrddongle">6.11 Circuit Designer dongle</a></h3> |
| 1699 |
|
| 1700 |
<p> |
| 1701 |
Circuit Designer dongle from The Falcon, needs the dongle in port B to start |
| 1702 |
the program, so in the console type: <code><a class="external" |
| 1703 |
href="commands.html#plugunplug">plug</a> joyportb circuit-designer-rd-dongle |
| 1704 |
</code>. |
| 1705 |
</p> |
| 1706 |
|
| 1707 |
<h2><a id="video">7. Video</a></h2> |
| 1708 |
|
| 1709 |
<p> |
| 1710 |
openMSX uses the OpenGL graphics library for all post processing (hence |
| 1711 |
the PP in SDLGL-PP, which is the name of the "renderer", the software component that generates |
| 1712 |
the graphical part of the emulation, the MSX 'screen'). This includes |
| 1713 |
scalers and other effects, but also the GUI... |
| 1714 |
Because of all this, openMSX runs best with a hardware accelerated |
| 1715 |
OpenGL library. See the Setup Guide for |
| 1716 |
<a class="external" href="setup.html#opengl">OpenGL performance tips</a>. |
| 1717 |
So, again, be aware that openMSX requires both your video |
| 1718 |
card and video driver to support at least OpenGL 2.0. Sometimes you need to |
| 1719 |
upgrade your driver to make it work. If your videocard or driver don't support |
| 1720 |
OpenGL 2.0, openMSX will not start up and report an error. |
| 1721 |
</p> |
| 1722 |
|
| 1723 |
<p> |
| 1724 |
Most video related settings can be found under the <span |
| 1725 |
class="menu-reference">Main menu bar → Settings → Video</span> menu. |
| 1726 |
The rest of this section describes more details about the settings you can find |
| 1727 |
there. For instance, for full screen mode, there is a checkbox in that menu, |
| 1728 |
which maps to the <code><a class="external" |
| 1729 |
href="commands.html#fullscreen">fullscreen</a></code> setting. |
| 1730 |
</p> |
| 1731 |
|
| 1732 |
<h3><a id="scalers">7.1 Scalers</a></h3> |
| 1733 |
|
| 1734 |
<p> |
| 1735 |
Most MSX screen modes are only 256×212 pixels big. This is quite small |
| 1736 |
for today's PC screen resolutions. That's why you have the possibility to |
| 1737 |
scale up the image. There are currently three possible scaling factors: 2, 3 |
| 1738 |
and 4. If you select 2, all MSX pixels are mapped to a 640×480 pixels PC |
| 1739 |
window, for 3 to a 960×720 pixel window and for 4 to the obvious |
| 1740 |
1280×960 window. The setting which determines this is called <code><a |
| 1741 |
class="external" href="commands.html#scale_factor">scale_factor</a></code>. In |
| 1742 |
general, the higher the factor, the better the output image is. |
| 1743 |
</p> |
| 1744 |
|
| 1745 |
<p> |
| 1746 |
There are also a number of scaling algorithms (setting <code><a class="external" |
| 1747 |
href="commands.html#scale_algorithm">scale_algorithm</a></code>) that can be |
| 1748 |
set. The scaling algorithm determines how exactly the mapping is done between |
| 1749 |
the MSX input screen and the PC output screen. As we render more pixels than |
| 1750 |
the normally visible MSX pixels, this allows for extra possibilities in the algorithms, like |
| 1751 |
deinterlacing and adding scanlines, blur, anti-aliasing (rounding of blocky |
| 1752 |
patters like stair cases) or even a Trinitron-like TV effect. |
| 1753 |
</p> |
| 1754 |
|
| 1755 |
<p> |
| 1756 |
openMSX contains the following scaling algorithms: |
| 1757 |
</p> |
| 1758 |
|
| 1759 |
<dl> |
| 1760 |
|
| 1761 |
<dt>simple</dt> |
| 1762 |
<dd> |
| 1763 |
This algorithm simply expands each MSX pixel to a square of |
| 1764 |
(scale_factor)×(scale_factor) PC pixels. |
| 1765 |
This is the default scaler and can be tuned to look like most CRT screens. |
| 1766 |
The image looks blocky, especially diagonal edges, but it does support |
| 1767 |
scanlines and blur. |
| 1768 |
</dd> |
| 1769 |
|
| 1770 |
<dt><a class="external" href="http://scale2x.sourceforge.net/">ScaleNx</a></dt> |
| 1771 |
<dd> |
| 1772 |
This scaler algorithm smoothes edges by using only original colors, so it will |
| 1773 |
not give any blur. It is fast and its image is less blocky than that of the |
| 1774 |
simple scaler. However, all corners are rounded, which does not look good on |
| 1775 |
all graphics. This scaler has not been properly implemented for scaling factors |
| 1776 |
of 4. |
| 1777 |
</dd> |
| 1778 |
|
| 1779 |
|
| 1780 |
<dt><a class="external" href="http://en.wikipedia.org/wiki/Hqx">hq</a></dt> |
| 1781 |
<dd> |
| 1782 |
This algorithm does a good job on most graphics; it avoids excessive blurring |
| 1783 |
and it keeps corners sharp. |
| 1784 |
On some graphics, it does not identify edges correctly, making those edges |
| 1785 |
blocky instead of smooth. |
| 1786 |
Especially with high scaling factors, it can give a very smooth looking image. |
| 1787 |
</dd> |
| 1788 |
|
| 1789 |
<dt>RGBTriplet</dt> |
| 1790 |
<dd> |
| 1791 |
This algorithm only works as intended when a scaling factor of 3 is used. Also, |
| 1792 |
it only works well for MSX screen modes of 256×212, which includes most |
| 1793 |
games. The idea of the algorithm is that each input pixel is mapped on a |
| 1794 |
triplet of pixels which represent the R(ed), G(reen) and B(lue) components of |
| 1795 |
the input pixel. This arrangement of RGB components is also used in the <a |
| 1796 |
class="external" href="http://en.wikipedia.org/wiki/Aperture_grille">Aperture |
| 1797 |
Grille</a> CRT's, also known as Trinitron and the modern TFT screens. You can |
| 1798 |
control the effect with the <code><a class="external" |
| 1799 |
href="commands.html#blur">blur</a></code> setting. This algorithm also includes |
| 1800 |
scan lines. |
| 1801 |
</dd> |
| 1802 |
|
| 1803 |
<dt>TV</dt> |
| 1804 |
<dd> |
| 1805 |
This algorithm tries to emulate the fact that on a CRT brighter pixels look |
| 1806 |
bigger than darker pixels. It has some minor flaws, but is already developed |
| 1807 |
far enough to make it available for you to try out. |
| 1808 |
</dd> |
| 1809 |
|
| 1810 |
</dl> |
| 1811 |
|
| 1812 |
<p> |
| 1813 |
A small (somewhat outdated) demonstration of some of the algorithms can be |
| 1814 |
found on <a class="external" href="http://openmsx.org/">the openMSX web |
| 1815 |
site</a>. |
| 1816 |
</p> |
| 1817 |
|
| 1818 |
<h3><a id="gamma">7.2 Gamma Correction</a></h3> |
| 1819 |
|
| 1820 |
<p> |
| 1821 |
PC monitors can have different gamma values than MSX monitors. |
| 1822 |
To compensate for this, openMSX has a gamma correction feature. |
| 1823 |
It is controlled by the <code><a class="external" |
| 1824 |
href="commands.html#gamma">gamma</a></code> setting. |
| 1825 |
A value of 1.0 disables gamma correction; a lower value makes the image darker; |
| 1826 |
a higher value makes it brighter. |
| 1827 |
</p> |
| 1828 |
|
| 1829 |
<p> |
| 1830 |
If you want to know what gamma correction really means, read <a |
| 1831 |
class="external" href="http://www.bberger.net/rwb/gamma.html">this page about |
| 1832 |
monitor gamma</a>. |
| 1833 |
The gamma correction value you can set in openMSX should be the gamma of your |
| 1834 |
PC screen divided by the gamma of the MSX screen. |
| 1835 |
I measured the gamma of my PC screen (TFT) at 2.0 and the gamma of my MSX |
| 1836 |
monitor at 2.5. That puts the gamma correction at 2.0 / 2.5 = 0.8. |
| 1837 |
So if I enter that value, the openMSX image will have comparable brightness to |
| 1838 |
the MSX image. |
| 1839 |
However, 0.8 is not the value I'm actually using: I prefer a brighter image |
| 1840 |
than my MSX monitor, so I chose to use a gamma correction of 1.1. |
| 1841 |
</p> |
| 1842 |
|
| 1843 |
<h3><a id="videoeffects">7.3 Special Effects</a></h3> |
| 1844 |
|
| 1845 |
<p> |
| 1846 |
openMSX contains a couple of special effects settings that can be applied to |
| 1847 |
the video output: |
| 1848 |
</p> |
| 1849 |
|
| 1850 |
<dl> |
| 1851 |
|
| 1852 |
<dt><code><a class="external" href="commands.html#deinterlace">deinterlace</a></code></dt> |
| 1853 |
<dd> |
| 1854 |
Interlacing is a technique to double the vertical resolution by splitting the |
| 1855 |
image into two frames: the first frame displays the even lines, the second |
| 1856 |
frame the odd lines. |
| 1857 |
The after glow on a TV and some processes in the human brain combine both |
| 1858 |
frames into a single image. However, this process is not perfect and you can |
| 1859 |
notice flickering, especially on horizontal lines. |
| 1860 |
The deinterlace feature combines the even and the odd frames into a single |
| 1861 |
output frame, thus eliminating the flicker. |
| 1862 |
The <code><a class="external" |
| 1863 |
href="commands.html#deinterlace">deinterlace</a></code> setting controls this |
| 1864 |
feature: |
| 1865 |
it can be on (enabled) or off (disabled); it is enabled by default. |
| 1866 |
</dd> |
| 1867 |
|
| 1868 |
<dt><code><a class="external" href="commands.html#deflicker">deflicker</a></code></dt> |
| 1869 |
<dd> |
| 1870 |
This filter detects pixels that alternate each frame between two different |
| 1871 |
colors and replaces those alternations with the average color. Such |
| 1872 |
'flickering' pixels can occur in software that rapidly changes between colors |
| 1873 |
to create the illusion of a wider color palette. It can also occur because of |
| 1874 |
'sprite flickering'. This setting is disabled by default because there aren't |
| 1875 |
that many situations where it really improves video quality, but it does have |
| 1876 |
a performance cost. |
| 1877 |
</dd> |
| 1878 |
|
| 1879 |
<dt><code><a class="external" href="commands.html#scanline">scanline</a></code></dt> |
| 1880 |
<dd> |
| 1881 |
On TV's and MSX monitors, you can see a small black space in between the |
| 1882 |
display lines, especially when using NTSC. |
| 1883 |
The scanlines feature simulates this by drawing some lines a bit darker. |
| 1884 |
This feature is disabled when a scaling algorithm other than |
| 1885 |
<code>simple</code>, <code>tv</code> or <code>RGBTriplet</code> is used. |
| 1886 |
</dd> |
| 1887 |
|
| 1888 |
<dt><code><a class="external" href="commands.html#blur">blur</a></code></dt> |
| 1889 |
<dd> |
| 1890 |
TV's and MSX monitors are less sharp than PC monitors: |
| 1891 |
neighbouring pixels tend to blur into each other. |
| 1892 |
The blur feature simulates this by interpolating neighbouring pixels. |
| 1893 |
The <code><a class="external" href="commands.html#blur">blur</a></code> |
| 1894 |
settings control this: |
| 1895 |
0 means no blur (completely sharp), 50 means some blur (like a monitor), |
| 1896 |
100 means maximum blur (like a TV). |
| 1897 |
All other values between 0 and 100 are also possible of course. |
| 1898 |
This feature is disabled when a scaling algorithm other than |
| 1899 |
<code>simple</code> or <code>RGBTriplet</code> is used. |
| 1900 |
</dd> |
| 1901 |
|
| 1902 |
<dt>after glow (<code><a class="external" href="commands.html#glow">glow</a></code>)</dt> |
| 1903 |
<dd> |
| 1904 |
The after glow feature blends each frame with the previous one. |
| 1905 |
This results in moving objects leaving a trail (motion blur). |
| 1906 |
The <code><a class="external" href="commands.html#glow">glow</a></code> setting |
| 1907 |
controls the amount of after glow: |
| 1908 |
0 means no after glow, 100 means maximum after glow. |
| 1909 |
</dd> |
| 1910 |
|
| 1911 |
<dt><code><a class="external" href="commands.html#noise">noise</a></code></dt> |
| 1912 |
<dd> |
| 1913 |
This setting controls the amount of pixel noise on the screen. |
| 1914 |
The <code><a class="external" href="commands.html#noise">noise</a></code> |
| 1915 |
setting controls the amount: |
| 1916 |
0 means no noise, 100 means maximum noise. The value is actually the deviation |
| 1917 |
of the colour of the original pixel and non-integer values are also possible. |
| 1918 |
</dd> |
| 1919 |
|
| 1920 |
<dt>display deformation (<code><a class="external" |
| 1921 |
href="commands.html#display_deform">display_deform</a></code>)</dt> |
| 1922 |
<dd> |
| 1923 |
This feature makes it possible to change the shape of the MSX screen. Here are the possibilities: |
| 1924 |
<ul> |
| 1925 |
<li><code>normal</code>: no deformation (default)</li> |
| 1926 |
<li><code>3d</code>: emulates a 3D view on an arcade cabinet's screen</li> |
| 1927 |
</ul> |
| 1928 |
</dd> |
| 1929 |
|
| 1930 |
</dl> |
| 1931 |
|
| 1932 |
<h3><a id="accuracy">7.4 Accuracy</a></h3> |
| 1933 |
|
| 1934 |
<p> |
| 1935 |
An advanced setting (which you can find under <span class="menu-reference">Main |
| 1936 |
menu bar → Settings → Video → Advanced (for debugging)</span> |
| 1937 |
(the <code><a class="external" |
| 1938 |
href="commands.html#accuracy">accuracy</a></code> setting) controls how often |
| 1939 |
the renderer is synchronised with the MSX video processor (VDP). |
| 1940 |
There are three options: |
| 1941 |
</p> |
| 1942 |
|
| 1943 |
<dl> |
| 1944 |
<dt>screen</dt> |
| 1945 |
<dd> |
| 1946 |
Synchronise once per screen (frame). |
| 1947 |
Good enough for most MSX1 software, but will break most raster effects. |
| 1948 |
</dd> |
| 1949 |
|
| 1950 |
<dt>line</dt> |
| 1951 |
<dd> |
| 1952 |
Synchronise at the start of a line. |
| 1953 |
This is good enough for most software. |
| 1954 |
This setting hides imperfections in raster effects, |
| 1955 |
which could be considered a useful feature. |
| 1956 |
</dd> |
| 1957 |
|
| 1958 |
<dt>pixel</dt> |
| 1959 |
<dd> |
| 1960 |
Synchronise at the exact pixel where a change occurs. |
| 1961 |
This is the most realistic setting and therefore set as the default. |
| 1962 |
To see demos like Unknown Reality (scope part) and Verti correctly, |
| 1963 |
you should use this setting. |
| 1964 |
Also, you will see any imperfections in raster effects |
| 1965 |
just like they occur on a real MSX. |
| 1966 |
</dd> |
| 1967 |
|
| 1968 |
</dl> |
| 1969 |
|
| 1970 |
<h3><a id="gfx9000">7.5 GFX9000/Video 9000</a></h3> |
| 1971 |
|
| 1972 |
<p> |
| 1973 |
openMSX has GFX9000 emulation. As there isn't that much software for it |
| 1974 |
available, it is not as complete, functional and optimized as the video |
| 1975 |
emulation of the classical MSX chips. |
| 1976 |
Despite of all this, most existing GFX9000 software runs pretty well, so we |
| 1977 |
found it worth sharing with you anyway. |
| 1978 |
</p> |
| 1979 |
|
| 1980 |
<p> |
| 1981 |
The real GFX9000 has an external video connector to which you can connect a |
| 1982 |
second monitor. We never took the trouble to |
| 1983 |
emulate a second monitor, however, so to see the GFX9000 in action, you need to switch the |
| 1984 |
videosource setting, which mimics a so-called SCART-switch in the real |
| 1985 |
world: <code>set |
| 1986 |
<a class="external" href="commands.html#videosource">videosource</a> GFX9000</code>. |
| 1987 |
This setting is only available when there are actually multiple video sources |
| 1988 |
available. In the GUI you can find it under <span |
| 1989 |
class="menu-reference">Main menu bar → Settings → Video → Video |
| 1990 |
source to display</span>. |
| 1991 |
</p> |
| 1992 |
|
| 1993 |
<p> |
| 1994 |
Alternatively, instead of the GFX9000 extension, you could use the |
| 1995 |
Video9000 extension (also built in in several Boosted MSX machine |
| 1996 |
configurations). The Video 9000 hardware has the possibility to superimpose the |
| 1997 |
GFX9000 video on top of the V99xx video (and this is practically the only |
| 1998 |
feature of the Video 9000 that is currently implemented). Software that is |
| 1999 |
Video 9000 aware, will tell the Video 9000 to show the GFX9000 if something |
| 2000 |
interesting is to be seen on the GFX9000 video output. So, for such software, |
| 2001 |
you do not have to switch video sources if you simply use the Video9000 |
| 2002 |
video source. When a Video 9000 is present in the currently running MSX |
| 2003 |
configuration, the Video9000 video source will be selected by default, to make |
| 2004 |
use of this superimpose feature. For programs not aware of Video 9000, you will |
| 2005 |
still have to switch video sources manually, just like on a real system. |
| 2006 |
</p> |
| 2007 |
|
| 2008 |
<p> |
| 2009 |
To get your normal MSX screen back, set the setting back to MSX. If you want to |
| 2010 |
toggle between them with a hotkey, it might be useful to bind a key for it. E.g.: <code><a |
| 2011 |
class="external" href="commands.html#bind">bind</a> F6 cycle <a |
| 2012 |
class="external" href="commands.html#videosource">videosource</a></code>.<br/> |
| 2013 |
<code><a class="external" href="commands.html#cycle">cycle</a></code> is a Tcl |
| 2014 |
command that cycles through the options of the setting in the parameter. |
| 2015 |
</p> |
| 2016 |
|
| 2017 |
<h3><a id="recording">7.6 Video Recording</a></h3> |
| 2018 |
|
| 2019 |
<p> |
| 2020 |
The video recorder enables you to record the audio and video rendered by |
| 2021 |
openMSX to an AVI file. The output video is in 320×240 resolution by |
| 2022 |
default, at 640×480 when using the <code>-doublesize</code> flag and at |
| 2023 |
960×720 when using the <code>-triplesize</code> flag. The video is |
| 2024 |
compressed with the ZMBV codec, a fast lossless compression algorithm that |
| 2025 |
works very well on 2D computer generated images. The <a class="external" |
| 2026 |
href="faq.html#codec">FAQ</a> contains more information about this codec. The |
| 2027 |
audio is uncompressed. |
| 2028 |
</p> |
| 2029 |
<p> |
| 2030 |
The recorded AVI file will not suffer from any hiccups, even if the emulation |
| 2031 |
ran too slow when you recorded it. The current video source (see previous |
| 2032 |
section) is recorded and the sound is recorded with the current <code><a |
| 2033 |
class="external" href="commands.html#frequency">frequency</a></code> setting. |
| 2034 |
If you change the <code><a class="external" |
| 2035 |
href="commands.html#frequency">frequency</a></code> setting during recording, |
| 2036 |
or, more importantly, if the software changes from PAL (50 Hz) to NTSC (60 Hz) |
| 2037 |
during recording, the video will get out of sync with the audio. Most of the <a |
| 2038 |
class="internal" href="#videoeffects">special effects</a> will not be recorded. |
| 2039 |
</p> |
| 2040 |
|
| 2041 |
<p> |
| 2042 |
If any stereo sound devices are present or any sound device has an off-center |
| 2043 |
balance, the recording will be made in stereo, otherwise it will be mono. If |
| 2044 |
a recording is made in mono and then a stereo sound device is added, you'll |
| 2045 |
receive a warning that stereo sound has been detected and that the two |
| 2046 |
channels will be mixed down to mono. You can prevent this from happening by |
| 2047 |
using the <code>-stereo</code> option to force a stereo recording even if |
| 2048 |
no stereo devices are present at the time you enter the command. You can also |
| 2049 |
force a mono recording with <code>-mono</code> to save space. |
| 2050 |
</p> |
| 2051 |
|
| 2052 |
<p> |
| 2053 |
In the GUI you can find the video recorder under <span |
| 2054 |
class="menu-reference">Main menu bar → Tools → Capture → |
| 2055 |
Audio/Video</span>, which will open a the corresponding window, in which you |
| 2056 |
can specify all the above mentioned settings. |
| 2057 |
</p> |
| 2058 |
|
| 2059 |
<p> |
| 2060 |
In the console, you can use the command <code><a class="external" |
| 2061 |
href="commands.html#record">record</a> start</code> to record to a default file |
| 2062 |
name, or you can use an additional parameter to specify a file. The command |
| 2063 |
<code><a class="external" href="commands.html#record">record</a> stop</code> |
| 2064 |
stops recording and <code><a class="external" |
| 2065 |
href="commands.html#record">record</a> toggle</code> toggles it. You can use |
| 2066 |
the <code>-audioonly</code> or <code>-videoonly</code> option to record only |
| 2067 |
sound or video. |
| 2068 |
</p> |
| 2069 |
<p> |
| 2070 |
If you want to put a recorded video on your web site, it is better to transcode |
| 2071 |
the audio to MP3 or Vorbis format, as this makes the file a lot smaller. |
| 2072 |
YouTube supports the ZMBV codec, so if you want to upload your recording you do |
| 2073 |
not need to transcode the video. If you want to share your video with people |
| 2074 |
who do not have (or want to install) the ZMBV codec, you should still transcode |
| 2075 |
it, of course. This can be done with programs such as <a class="external" |
| 2076 |
href="http://www.virtualdub.org/">Virtual Dub</a> (Windows) or <a |
| 2077 |
class="external" href="http://www.mplayerhq.hu/">MPlayer's MEncoder</a> |
| 2078 |
(Linux/UNIX). For YouTube you may want to use the command <code><a |
| 2079 |
class="external" href="commands.html#record">record_chunks</a></code> instead: |
| 2080 |
it will enable you to chop up your video in several parts and enables |
| 2081 |
<code>-doublesize</code> automatically. |
| 2082 |
</p> |
| 2083 |
|
| 2084 |
<p> |
| 2085 |
Recording as explained above will happen in real-time. This can be annoying if |
| 2086 |
you want to make a demonstration video, because you all mistakes will be |
| 2087 |
recorded as well. To work around this, you can also use the <code><a |
| 2088 |
class="external" href="commands.html#reverse">reverse</a></code> feature during |
| 2089 |
the scene you want to record. After the scene, reverse to the beginning, start |
| 2090 |
the recording as explained above and let the scene replay relaxedly. You can |
| 2091 |
even speed it up using the <a class="external" |
| 2092 |
href="commands.html#throttle">throttle</a> setting. This method of recording is |
| 2093 |
also useful when real-time recording has a big impact on the performance of |
| 2094 |
openMSX on your hardware. See also <a class="internal" href="#reverse">the |
| 2095 |
chapter about this feature</a>. |
| 2096 |
</p> |
| 2097 |
|
| 2098 |
<h2><a id="audio">8. Audio</a></h2> |
| 2099 |
|
| 2100 |
<h3><a id="audiosettings">8.1 Audio Settings</a></h3> |
| 2101 |
|
| 2102 |
<p> |
| 2103 |
Most audio related settings can be found under the <span |
| 2104 |
class="menu-reference">Main menu bar → Settings → Sound</span> menu. |
| 2105 |
</p> |
| 2106 |
|
| 2107 |
<p> |
| 2108 |
There is a <code><a class="external" |
| 2109 |
href="commands.html#master_volume">master_volume</a></code> setting, which |
| 2110 |
controls the overall output volume of openMSX (it applies to all sound |
| 2111 |
devices). Volume 0 means no sound, volume 100 is maximum. |
| 2112 |
</p> |
| 2113 |
|
| 2114 |
<p> |
| 2115 |
There is also a <code><a class="external" |
| 2116 |
href="commands.html#mute">mute</a></code> setting, to disable all sound from |
| 2117 |
openMSX at once. It can be on (muted) or off (sound is audible). By default, |
| 2118 |
mute is bound to the F12 key. |
| 2119 |
</p> |
| 2120 |
|
| 2121 |
<p> |
| 2122 |
There are also settings for each emulated sound device. These can be found |
| 2123 |
under the <span class="menu-reference">Main menu bar → Settings → |
| 2124 |
Sound → Show sound chip settings</span> option in the menu. |
| 2125 |
</p> |
| 2126 |
|
| 2127 |
<p> |
| 2128 |
For each sound device there is a volume setting. |
| 2129 |
Volume 0 means no sound, volume 100 is maximum. In the console you can do this, for example: <code>set <a |
| 2130 |
class="external" href="commands.html#soundchip_volume">"MSX Music_volume"</a> |
| 2131 |
50</code>. |
| 2132 |
</p> |
| 2133 |
|
| 2134 |
<p> |
| 2135 |
For each sound device, you can control the distribution of the sound output of |
| 2136 |
this chip over the left and right channel, with the balance setting. This is |
| 2137 |
very similar to the balance knob on (older?) hifi equipment. |
| 2138 |
Example: <code>set <a class="external" |
| 2139 |
href="commands.html#soundchip_balance">PSG_balance</a> -100</code>, which sets |
| 2140 |
the PSG entirely to the left channel. Any sound device can also be individually |
| 2141 |
(un)muted using the <a class="external" |
| 2142 |
href="commands.html#mute_channels">mute_channels</a> command. |
| 2143 |
</p> |
| 2144 |
|
| 2145 |
<p> |
| 2146 |
If you'd like to apply some special effects to the PSG sound, you should take a |
| 2147 |
look at the <a class="external" |
| 2148 |
href="commands.html#psg_vibrato_frequency">vibrato</a> and <a |
| 2149 |
class="external" href="commands.html#psg_detune_frequency">detune</a> |
| 2150 |
(both percent and frequency) settings. |
| 2151 |
</p> |
| 2152 |
|
| 2153 |
<h3><a id="midi">8.2 MIDI</a></h3> |
| 2154 |
|
| 2155 |
<p> |
| 2156 |
Currently, openMSX supports the following MSX MIDI interfaces: |
| 2157 |
</p> |
| 2158 |
<ul> |
| 2159 |
<li>MSX-MIDI of the MSX turboR GT and the μ・PACK,</li> |
| 2160 |
<li>the MIDI interface of the Philips Music Module (NMS 1205),</li> |
| 2161 |
<li>the MIDI interface of the Yamaha SFG-01 and SFG-05 module (also present in the Yamaha CX5M series of machines),</li> |
| 2162 |
<li>the FAC MIDI Interface, and</li> |
| 2163 |
<li>the JVC (UK) MSX MIDI interface.</li> |
| 2164 |
</ul> |
| 2165 |
<p> |
| 2166 |
To use MIDI, start openMSX with a machine that has a MIDI interface built in, |
| 2167 |
or add one of the mentioned MIDI interface extensions. Then plug a MIDI out |
| 2168 |
and/or MIDI in device into that MSX MIDI interface using the GUI |
| 2169 |
<span class="menu-reference">Main menu bar → Connector</span> menu or the |
| 2170 |
openMSX <a class="internal" href="#console">console</a>. |
| 2171 |
</p> |
| 2172 |
|
| 2173 |
<h4>MIDI Out</h4> |
| 2174 |
|
| 2175 |
<p> |
| 2176 |
You can connect the MIDI out of the MSX to a host MIDI device, such as a |
| 2177 |
physical MIDI out port, a soft synthesizer or a sequencer program. On Windows, |
| 2178 |
Linux and macOS, host MIDI devices are made available as pluggables in openMSX. |
| 2179 |
On macOS, you can opt to instead select <code>Virtual OUT</code> to create a |
| 2180 |
virtual MIDI port for Mac MIDI software to connect to. |
| 2181 |
</p> |
| 2182 |
|
| 2183 |
<p> |
| 2184 |
For example, use the machine <code>Panasonic_FS-A1GT</code> and plug into the |
| 2185 |
<a class="external" href="https://sourceforge.net/projects/munt/">Munt</a> soft |
| 2186 |
synthesizer (MT-32 emulator) using <span class="menu-reference">Main menu bar |
| 2187 |
→ Connectors</span> menu, or with the console command <code><a |
| 2188 |
class="external" href="commands.html#plugunplug">plug</a> msx-midi-out Munt\ |
| 2189 |
MT-32</code>. |
| 2190 |
</p> |
| 2191 |
<p> |
| 2192 |
The exact naming of the host MIDI devices differs per platform. In the console |
| 2193 |
you can use tab completion to see the options: type <code>plug |
| 2194 |
msx-midi-out</code> and hit TAB twice. |
| 2195 |
</p> |
| 2196 |
|
| 2197 |
<p> |
| 2198 |
The <code>midi-out-logger</code> MIDI device is available on all platforms and |
| 2199 |
logs MIDI events to a file. |
| 2200 |
</p> |
| 2201 |
<p> |
| 2202 |
You can specify the file to log to using <code>set |
| 2203 |
<a class="external" |
| 2204 |
href="commands.html#midi-out-logfilename">midi-out-logfilename</a></code>. |
| 2205 |
The log is a raw binary log of the bytes written by the MIDI interface, with no |
| 2206 |
timing information. Therefore its usefulness is mostly limited to debugging. |
| 2207 |
</p> |
| 2208 |
<p> |
| 2209 |
On UNIX-like systems, it is possible to log to a MIDI device node, for example |
| 2210 |
<code>/dev/midi</code> and configure the sound system to send those notes to a |
| 2211 |
soft synthesizer. This is harder to configure than using for example the ALSA |
| 2212 |
MIDI out device, so it's only recommended when no platform-specific MIDI |
| 2213 |
devices are available in openMSX. On MSX Resource Center there is <a |
| 2214 |
class="external" |
| 2215 |
href="http://www.msx.org/forum/semi-msx-talk/emulation/openmsx-timidity">a |
| 2216 |
forum thread</a> which describes how to connect openMSX to Timidity via |
| 2217 |
<code>/dev/midi</code>. |
| 2218 |
</p> |
| 2219 |
|
| 2220 |
<h4>MIDI In</h4> |
| 2221 |
|
| 2222 |
<p> |
| 2223 |
Vice versa, the MIDI in port can also receive data from the system by plugging |
| 2224 |
a device into <code>msx-midi-in</code> (for the Panasonic FS-A1GT; use the |
| 2225 |
appropriate connector name for other devices). Analogous to the above mentioned |
| 2226 |
outputs you can connect a <code>midi-in-reader</code> which reads from a file |
| 2227 |
or <code>/dev/midi</code> on Linux. On Windows and macOS available MIDI devices |
| 2228 |
show up as separate pluggables. On macOS a <code>Virtual IN</code> port is |
| 2229 |
available as well. |
| 2230 |
</p> |
| 2231 |
|
| 2232 |
<h3><a id="soundlogger">8.3 Recording Audio to File</a></h3> |
| 2233 |
|
| 2234 |
<p> |
| 2235 |
openMSX records the sound at the exact speed at which it should be produced, no |
| 2236 |
matter the speed at which the emulation was running while recording. Note that |
| 2237 |
recording sound to the uncompressed WAV format will take a lot of disk space: |
| 2238 |
at 44.1 kHz it will take about 176 kB per second. |
| 2239 |
</p> |
| 2240 |
|
| 2241 |
<p> |
| 2242 |
In the GUI you can find the audio recorder under <span |
| 2243 |
class="menu-reference">Main menu bar → Tools → Capture → |
| 2244 |
Audio/Video</span>, which will open a the audio/video recording window. Just |
| 2245 |
select <span class="menu-reference">only Audio</span> to log to said WAV file. |
| 2246 |
<p> |
| 2247 |
|
| 2248 |
<p> |
| 2249 |
The underlying console command to start the recording of sound is <code><a |
| 2250 |
class="external" href="commands.html#soundlog">soundlog</a> start</code>. It |
| 2251 |
will automatically choose a file name and save it in the <code>soundlogs</code> |
| 2252 |
directory in your personal openMSX folder. You can also add an extra parameter |
| 2253 |
to specify the filename for the new WAV file. To stop recording, use <code><a |
| 2254 |
class="external" href="commands.html#soundlog">soundlog</a> stop</code>. You |
| 2255 |
can toggle the recording status using <code><a class="external" |
| 2256 |
href="commands.html#soundlog">soundlog</a> toggle</code>, which is useful if |
| 2257 |
you <code><a class="external" href="commands.html#bind">bind</a></code> this |
| 2258 |
command to a hotkey. |
| 2259 |
</p> |
| 2260 |
|
| 2261 |
<p> |
| 2262 |
There is also an advanced feature for recording audio to file: you can record |
| 2263 |
individual channels of sound chips to individual files on disk. The sound is in |
| 2264 |
the native frequency of the sound chip this time, which means that for chips |
| 2265 |
like PSG or SCC (which run at very high frequencies), the files will be huge. |
| 2266 |
(You have been warned!) This feature can be controlled in the GUI via <span |
| 2267 |
class="menu-reference">Main menu bar → Settings → Sound → Show |
| 2268 |
sound chip settings</span> and in that window click on the "channels" checkbox, |
| 2269 |
which opens a window where you can fill in a file name for each channel you |
| 2270 |
want to record with. Perhaps it is easiest to control from the console with the |
| 2271 |
<code><a class="external" |
| 2272 |
href="commands.html#record_channels">record_channels</a></code> command. Note |
| 2273 |
that in contrast to the <code><a class="external" |
| 2274 |
href="commands.html#soundlog">soundlog</a></code> command, the output file of |
| 2275 |
this command ends up in the current directory and not in a special directory. |
| 2276 |
We hope you can use this command to study the fantastic compositions of MSX |
| 2277 |
software and make great remakes of them. |
| 2278 |
</p> |
| 2279 |
|
| 2280 |
<h2><a id="usefulextras">9. Useful Extras</a></h2> |
| 2281 |
|
| 2282 |
<h3><a id="savestate">9.1 Saving/Loading the State of the Machine</a></h3> |
| 2283 |
|
| 2284 |
<p> |
| 2285 |
A feature of emulators which is particularly useful is saving the state of the |
| 2286 |
emulated machine to a file, in order to load it again later and continue |
| 2287 |
exactly where you left off when saving. Not only useful for games, but also for |
| 2288 |
debugging or testing. For openMSX we designed this feature in such a way |
| 2289 |
that it is trying really hard to be future proof. So, you |
| 2290 |
don't have to be afraid to upgrade to a new version of openMSX: your save |
| 2291 |
states will remain usable! |
| 2292 |
</p> |
| 2293 |
|
| 2294 |
<p> |
| 2295 |
In the GUI's <span class="menu-reference">Main menu bar → Save |
| 2296 |
state</span> menu you find all options to (quick) load and save states and even |
| 2297 |
more. </p> |
| 2298 |
|
| 2299 |
<p> |
| 2300 |
The easiest way to use it is by using the keyboard shortcuts for quickly saving |
| 2301 |
and loading a state, see the shortcut hints in the aforementioned menu and also the <a class="internal" href="#keymapping">key mapping |
| 2302 |
section</a>. These shortcuts basically use the <a class="external" |
| 2303 |
href="commands.html#savestate">savestate</a> and loadstate commands, with the |
| 2304 |
parameter <code>quicksave</code>, i.e. they use a savestate file with the name |
| 2305 |
'quicksave'. You can also use the commands directly yourself, with the argument |
| 2306 |
as the name of the slot you save the state to (use TAB or the <code><a |
| 2307 |
class="external" href="commands.html#savestate">list_savestates</a></code> |
| 2308 |
command to see your previously saved states). Without having to browse the file |
| 2309 |
system of your computer, you can also conveniently delete existing save games |
| 2310 |
with the <code><a class="external" |
| 2311 |
href="commands.html#savestate">delete_savestate</a></code> command. |
| 2312 |
</p> |
| 2313 |
|
| 2314 |
<p> |
| 2315 |
Note that when saving the state of the machine, a screenshot will also be saved |
| 2316 |
with it, so that those could be used for save state browsing. |
| 2317 |
</p> |
| 2318 |
|
| 2319 |
<h3><a id="reverse">9.2 Reverse</a></h3> |
| 2320 |
|
| 2321 |
<p> |
| 2322 |
Inspired by the meisei MSX emulator, openMSX also has a reverse feature. |
| 2323 |
This enables you to go back in MSX time, so you can correct mistakes in your |
| 2324 |
game play or you can watch what you did (and also record a video of it). |
| 2325 |
</p> |
| 2326 |
|
| 2327 |
<p> |
| 2328 |
You can go back in time a second using the <a |
| 2329 |
class="internal" href="#keymapping">key binding</a> for this: PageUp. Once you |
| 2330 |
went back, openMSX will replay whatever you did when you were at this time for |
| 2331 |
the first time, until it got at the point where you went back. From then on, |
| 2332 |
everything will continue as normal. If you touched any control of your MSX |
| 2333 |
during replay, you have indicated to take over from the replay. If you do that, |
| 2334 |
the rest of the replay is erased (openMSX forgets that that future ever |
| 2335 |
happened). This is the typical way to correct mistakes using this feature. |
| 2336 |
</p> |
| 2337 |
|
| 2338 |
<p> |
| 2339 |
While replaying, you can also jump forward in time ("Back to the Future") using |
| 2340 |
PageDown. Also, you can go back a specific amount of seconds or to an absolute |
| 2341 |
moment in (MSX) time, all using the <code><a class="external" |
| 2342 |
href="commands.html#reverse">reverse</a></code> command. (This can also be |
| 2343 |
useful when you're developing/debugging MSX software.) |
| 2344 |
</p> |
| 2345 |
|
| 2346 |
<p> |
| 2347 |
If all of this sounds a bit confusing, you can use the reverse bar (by default, |
| 2348 |
it's placed in the bottom right corner, hover there in the main openMSX window |
| 2349 |
to make it appear), which will show you a visualisation of all of this on |
| 2350 |
screen. The bar represents the time while the feature was enabled and shows the |
| 2351 |
current moment in time (the red indicator). You can click on it to jump back |
| 2352 |
and forward in time. The vertical lines indicate times when snapshots were |
| 2353 |
made. The bar will fade out after a while, but hovering your cursor over it |
| 2354 |
makes it reappear. If you want to get rid of the bar, toggle this setting in |
| 2355 |
the GUI menu: <span class="menu-reference">Main menu bar → Save state |
| 2356 |
→ Reverse/replay settings → Show reverse bar</span>. (This will not |
| 2357 |
turn off the reverse feature itself.) |
| 2358 |
</p> |
| 2359 |
|
| 2360 |
<p> |
| 2361 |
If you want to disable the reverse feature, you can use <span |
| 2362 |
class="menu-reference">Main menu bar → Save state → Reverse/replay |
| 2363 |
settings → Enable reverse/replay</span> or the underlying <code><a |
| 2364 |
class="external" href="commands.html#reverse">reverse stop</a></code> console command. |
| 2365 |
And if you don't want it to restart again anymore, uncheck the <span |
| 2366 |
class="menu-reference">Main menu bar → Save state → Reverse/replay |
| 2367 |
settings → Auto enable reverse</span> <a class="external" |
| 2368 |
href="commands.html#auto_enable_reverse">setting</a>. |
| 2369 |
</p> |
| 2370 |
|
| 2371 |
<p> |
| 2372 |
If you want to save a very compact recording of what you did, or want to have |
| 2373 |
the possibility to start off in the middle of a recording, you can save your |
| 2374 |
complete replay to a file with <span |
| 2375 |
class="menu-reference">Main menu bar → Save state → Save |
| 2376 |
replay</span> or the <code><a class="external" |
| 2377 |
href="commands.html#reverse">reverse savereplay</a></code> command. They can |
| 2378 |
also be loaded of course, with <span |
| 2379 |
class="menu-reference">Main menu bar → Save state → Load |
| 2380 |
replay</span> or <code><a class="external" |
| 2381 |
href="commands.html#reverse">reverse loadreplay</a></code>. |
| 2382 |
</p> |
| 2383 |
|
| 2384 |
<h3><a id="trainer">9.3 Game Trainer</a></h3> |
| 2385 |
|
| 2386 |
<p> |
| 2387 |
openMSX includes a game trainer system. You start with it by using the GUI |
| 2388 |
menu: <span class="menu-reference">Main menu bar → Tools → Trainer Selector</span> This will open a window in which you |
| 2389 |
must first select the game you want to use a trainer for from the list of |
| 2390 |
supported games. When a game is selected, you see the list of cheats displayed |
| 2391 |
for the game, where you can also toggle the different cheats you want to |
| 2392 |
activate. |
| 2393 |
</p> |
| 2394 |
|
| 2395 |
<p> |
| 2396 |
As with most openMSX functionality, the trainers can also be used from the <a |
| 2397 |
class="internal" href="#console">console</a>, and even there it is very easy to |
| 2398 |
use. As always, you could type: <code>help <a class="external" |
| 2399 |
href="commands.html#trainer">trainer</a></code>, for some basic help. |
| 2400 |
</p> |
| 2401 |
|
| 2402 |
<p> |
| 2403 |
Suppose you want to cheat on Metal Gear. Then it would be useful to type: |
| 2404 |
<code>trainer Metal[TAB]</code>, which will expand to: <code>trainer Metal\ |
| 2405 |
Gear</code>. When you then press enter, you see which cheats are available in |
| 2406 |
the Metal Gear trainer. You can activate them by typing e.g.: <code>trainer |
| 2407 |
Metal\ Gear 1 2 3 4</code>. This will activate (toggle) the first 4 cheats (as |
| 2408 |
the list will tell you which is printed after the command: the crosses indicate an |
| 2409 |
active cheat). You can also use the descriptions instead of the numbers: |
| 2410 |
<code>trainer Metal\ Gear "enemy 1 gone" "enemy 2 gone"</code>. Or, if you want |
| 2411 |
to activate all cheats you can simply type: <code>trainer Metal\ Gear |
| 2412 |
all</code>. |
| 2413 |
</p> |
| 2414 |
|
| 2415 |
<p> |
| 2416 |
If this sounds a bit difficult for you, just try it out. It's really much |
| 2417 |
easier when you actually work with it. |
| 2418 |
As always in the console, using TAB to complete your commands and their options |
| 2419 |
proves to be very useful! |
| 2420 |
</p> |
| 2421 |
|
| 2422 |
<h3><a id="debugdevice">9.4 Debug Device</a></h3> |
| 2423 |
|
| 2424 |
<p> |
| 2425 |
This chapter describes how an MSX programmer can use the openMSX built-in debug |
| 2426 |
device. This is an artificial MSX device that is connected to an MSX I/O port. |
| 2427 |
It can be used to send debug messages to the host operating system. |
| 2428 |
</p> |
| 2429 |
|
| 2430 |
<p> |
| 2431 |
Note that openMSX also contains built-in debugging functions, which can be |
| 2432 |
accessed with the <code><a class="external" |
| 2433 |
href="commands.html#debug">debug</a></code> console command. With that debugger |
| 2434 |
you can read and write all registers and memory of almost all devices that are |
| 2435 |
supported in openMSX. It also supports break points, watch points and stepping. |
| 2436 |
See the <span class="menu-reference">Main menu |
| 2437 |
bar → Debugger</span> menu for the most common debugging options. |
| 2438 |
</p> |
| 2439 |
|
| 2440 |
<h4><a id="debugdeviceenable">9.4.1 Enabling the Debug Device</a></h4> |
| 2441 |
|
| 2442 |
<p> |
| 2443 |
To enable the debug device, insert the <code>debugdevice</code> extension. To |
| 2444 |
do this when starting openMSX, simply add <code>-ext debugdevice</code> to the |
| 2445 |
openMSX command line. If openMSX is already running, you can use the |
| 2446 |
<code><a class="external" href="commands.html#ext">ext</a></code> |
| 2447 |
console command. |
| 2448 |
</p> |
| 2449 |
|
| 2450 |
<p> |
| 2451 |
You can use the <code><a class="external" |
| 2452 |
href="commands.html#debugoutput">Debug Device output</a></code> setting to specify the |
| 2453 |
file name to write the debug output to. |
| 2454 |
</p> |
| 2455 |
|
| 2456 |
<h4><a id="debugdeviceports">9.4.2 Output Ports</a></h4> |
| 2457 |
|
| 2458 |
<p> |
| 2459 |
Controlling the device is done from within an MSX program. For this purpose, the |
| 2460 |
output ports 0x2E and 0x2F are used. The first port is the Mode Set Register. |
| 2461 |
Bytes sent to this port have the following meaning. |
| 2462 |
</p> |
| 2463 |
<table> |
| 2464 |
<tr> <th>bit(s)</th><th>meaning</th> </tr> |
| 2465 |
<tr> <td>7 </td> <td>unused</td> </tr> |
| 2466 |
<tr> <td>6 </td> <td>line feed mode (0 = line feed at mode change, 1 no line feed)</td> </tr> |
| 2467 |
<tr> <td>5-4</td> <td>output mode (0 = OFF, 1 = single byte, 2 = multi byte)</td> </tr> |
| 2468 |
<tr> <td>3-0</td> <td>mode-specific parameters (see below)</td> </tr> |
| 2469 |
</table> |
| 2470 |
|
| 2471 |
<p> |
| 2472 |
When using mode 1, single byte mode, the lower 4 bits each enable a particular |
| 2473 |
output format: |
| 2474 |
</p> |
| 2475 |
<table> |
| 2476 |
<tr> <th>bit(s)</th><th>meaning</th> </tr> |
| 2477 |
<tr> <td>3</td> <td>ASCII mode on/off</td> </tr> |
| 2478 |
<tr> <td>2</td> <td>decimal mode on/off</td> </tr> |
| 2479 |
<tr> <td>1</td> <td>binary mode on/off</td> </tr> |
| 2480 |
<tr> <td>0</td> <td>hexadecimal mode on/off</td> </tr> |
| 2481 |
</table> |
| 2482 |
<p> |
| 2483 |
So, every parameter bit turns an output format on or off and more than one |
| 2484 |
output format can be specified at the same time. |
| 2485 |
</p> |
| 2486 |
|
| 2487 |
<p> |
| 2488 |
The parameters for mode 2 (multi byte mode) are as follows: |
| 2489 |
</p> |
| 2490 |
<table> |
| 2491 |
<tr> <th>bit(s)</th><th>meaning</th> </tr> |
| 2492 |
<tr> <td>3-2</td> <td>unused</td> </tr> |
| 2493 |
<tr> <td>1-0</td> <td>mode (0 = hex, 1 = binary, 2 = decimal, 3 = ASCII mode)</td> </tr> |
| 2494 |
</table> |
| 2495 |
|
| 2496 |
<h4><a id="debugdevicemode1">9.4.3 Single Byte Mode</a></h4> |
| 2497 |
|
| 2498 |
<p> |
| 2499 |
In mode 1, any write to port 0x2F will result in output. This way, the |
| 2500 |
programmer can see if a specific address is reached by adding a single |
| 2501 |
<code>OUT</code> to the code. The output depends on the parameters set with the |
| 2502 |
mode register. Each bit represents a specific format, and by turning the bits |
| 2503 |
on and off, the programmer can decide which formats should be used. |
| 2504 |
</p> |
| 2505 |
|
| 2506 |
<p> |
| 2507 |
Here is an example: |
| 2508 |
</p> |
| 2509 |
<pre> |
| 2510 |
LD A,65 |
| 2511 |
OUT ($2f),A |
| 2512 |
</pre> |
| 2513 |
|
| 2514 |
<p> |
| 2515 |
This will give the following output: |
| 2516 |
</p> |
| 2517 |
|
| 2518 |
<pre>41h 01000001b 065 'A' emutime: 36407199578 |
| 2519 |
</pre> |
| 2520 |
<p> |
| 2521 |
(when all bits are on, mode register = 0x1F)<br/> |
| 2522 |
or |
| 2523 |
</p> |
| 2524 |
<pre>41h 065 'A' emutime: 36407199578 |
| 2525 |
</pre> |
| 2526 |
<p> |
| 2527 |
(when the binary bit is off, mode register = 0x1D)<br/> |
| 2528 |
or |
| 2529 |
</p> |
| 2530 |
<pre>41h emutime: 36407199578 |
| 2531 |
</pre> |
| 2532 |
<p> |
| 2533 |
(when only the hexbit is on, mode register = 0x11)<br/> |
| 2534 |
and so on. |
| 2535 |
</p> |
| 2536 |
|
| 2537 |
<p> |
| 2538 |
The EmuTime part is a special number that keeps track of the openMSX emulation. |
| 2539 |
The larger this number is, the later the event took place. This is a great way |
| 2540 |
to get an idea of the timing of things. |
| 2541 |
</p> |
| 2542 |
<p> |
| 2543 |
If the character to print is a special character, like carriage return, |
| 2544 |
linefeed, beep or tab, the character between the ' ' will be a dot (.) and the |
| 2545 |
normal character is 'displayed' at the very end of the line, so it won't mess up |
| 2546 |
the layout of the whole line. |
| 2547 |
</p> |
| 2548 |
|
| 2549 |
|
| 2550 |
<h4><a id="debugdevicemode2">9.4.4 Multi Byte Mode</a></h4> |
| 2551 |
|
| 2552 |
<p> |
| 2553 |
Unlike mode 1, the data in this mode is always shown in one mode only. It's |
| 2554 |
either in hex mode, binary mode, decimal mode or ASCII mode, but never a |
| 2555 |
combination. Also the EmuTime bit is left out. |
| 2556 |
</p> |
| 2557 |
|
| 2558 |
<p> |
| 2559 |
Here is an example: |
| 2560 |
</p> |
| 2561 |
<pre> |
| 2562 |
LD A,xx |
| 2563 |
OUT ($2e),A |
| 2564 |
LD A,$41 |
| 2565 |
OUT ($2f),A |
| 2566 |
OUT ($2f),A |
| 2567 |
OUT ($2f),A |
| 2568 |
</pre> |
| 2569 |
|
| 2570 |
<p> |
| 2571 |
If we substitute <code>$20</code> for <code>xx</code>, we get: |
| 2572 |
</p> |
| 2573 |
<pre>41h 41h 41h</pre> |
| 2574 |
<p> |
| 2575 |
and if we substitute <code>$22</code> for <code>xx</code>, we get: |
| 2576 |
</p> |
| 2577 |
<pre>065 065 065</pre> |
| 2578 |
<p> |
| 2579 |
The extra zero is added to keep alignment. Finally, if we want ASCII |
| 2580 |
output, all we need to do is change <code>xx</code> for <code>$23</code>: |
| 2581 |
</p> |
| 2582 |
<pre>AAA</pre> |
| 2583 |
<p> |
| 2584 |
In this special case, the space in between the data is left out. Any special |
| 2585 |
character like carriage return, linefeed, beep or tab will be printed as you |
| 2586 |
would expect. |
| 2587 |
</p> |
| 2588 |
|
| 2589 |
<h3><a id="programmabledevice">9.5 Programmable Device</a></h3> |
| 2590 |
|
| 2591 |
<p> |
| 2592 |
This chapter describes briefly the built-in programmable device, a resource that |
| 2593 |
could prove useful for driver or hardware developers writing and debugging |
| 2594 |
software on openMSX instead of a real MSX. The programmable device is a virtual |
| 2595 |
MSX device that can be connected on the fly to a user-defined list of I/O ports. |
| 2596 |
It can be used to create a two-way communication between the virtual computer |
| 2597 |
and the host operating system by using the high-level Tcl language that openMSX |
| 2598 |
provides. It goes without saying that you must know how to use the Tcl language |
| 2599 |
to use this feature. |
| 2600 |
</p> |
| 2601 |
<p> |
| 2602 |
Note that this is not intended to be used as a drop-in replacement for |
| 2603 |
resource-intensive hardware like VDPs. Tcl is overall a very slow language, but |
| 2604 |
a programmable device opens up possibilities for using openMSX as a development |
| 2605 |
tool that were not possible before. |
| 2606 |
</p> |
| 2607 |
<p> |
| 2608 |
Note there's some overlap between this device and the <code><a class="external" |
| 2609 |
href="commands.html#debug">debug watchpoint create -type read_io/write_io</a></code> |
| 2610 |
command. Both can be used to make Tcl react to I/O read/write operations. This |
| 2611 |
device is more suited for completely new functionality. The debug command is |
| 2612 |
more suited to intercept communication with existing MSX devices. |
| 2613 |
</p> |
| 2614 |
|
| 2615 |
<h4><a id="programmabledeviceenable">9.5.1 Enabling the Programmable Device</a></h4> |
| 2616 |
|
| 2617 |
<p> |
| 2618 |
To enable the programmable device, insert the <code>programmabledevice</code> |
| 2619 |
extension. To do this when starting openMSX, simply add |
| 2620 |
<code>-ext programmabledevice</code> to the openMSX command line. If openMSX is |
| 2621 |
already running, you can use the |
| 2622 |
<code><a class="external" href="commands.html#ext">ext</a></code> console command. |
| 2623 |
</p> |
| 2624 |
|
| 2625 |
<h4><a id="programmabledeviceports">9.5.2 Device Ports and callbacks</a></h4> |
| 2626 |
|
| 2627 |
<p> |
| 2628 |
Device ports are a list of I/O ports connected between the guest computer and |
| 2629 |
the Tcl environment. This means that anything a Z80 assembly program sends to |
| 2630 |
one of these I/O ports using an OUT instruction automatically calls an "output |
| 2631 |
callback" (a Tcl procedure) to receive the data on the Tcl side. You must |
| 2632 |
declare your own output callback, otherwise the programmable device will do |
| 2633 |
nothing when it receives a byte. Your callback must have two parameters: port |
| 2634 |
and value (2 8-bit values) the return value from this callback is ignored. |
| 2635 |
</p> |
| 2636 |
<p> |
| 2637 |
Alternatively, anything a Z80 assembly program reads from one of these I/O ports |
| 2638 |
using an IN instruction automatically calls an "input callback" on the Tcl side. |
| 2639 |
That callback produces the value that will be received by the Z80. You also must |
| 2640 |
declare your own input callback, otherwise the programmable device will return |
| 2641 |
0xFF. An input callback receives a (8-bit) port number as the only parameter, |
| 2642 |
and it must return an 8-bit value. |
| 2643 |
</p> |
| 2644 |
<p> |
| 2645 |
The third kind of callback you can create is the "reset callback". This one has |
| 2646 |
no parameters and the return value is ignored. It can be useful for setting back |
| 2647 |
an initial state when the MSX reboots. |
| 2648 |
</p> |
| 2649 |
<p> |
| 2650 |
You can check the 4 settings that Programmable Device uses with the <a |
| 2651 |
class="external" href="commands.html#help">help</a> command, but briefly: |
| 2652 |
</p> |
| 2653 |
<div class="commandline"> |
| 2654 |
<a class="external" href="commands.html#set">set</a> {Programmable Device |
| 2655 |
ports} {6 7} |
| 2656 |
</div> |
| 2657 |
<p> |
| 2658 |
tracks I/O ports 6 and 7. |
| 2659 |
</p> |
| 2660 |
<div class="commandline"> |
| 2661 |
<a class="external" href="commands.html#set">set</a> {Programmable Device |
| 2662 |
reset callback} "my_reset_proc" |
| 2663 |
</div> |
| 2664 |
<p> |
| 2665 |
connects the reset event with your previously declared "my_reset_proc" callback. |
| 2666 |
</p> |
| 2667 |
<div class="commandline"> |
| 2668 |
<a class="external" href="commands.html#set">set</a> {Programmable Device |
| 2669 |
output callback} "my_output_proc" |
| 2670 |
</div> |
| 2671 |
<p> |
| 2672 |
connects the "OUT instruction" event with your previously declared |
| 2673 |
"my_output_proc" callback. |
| 2674 |
</p> |
| 2675 |
<div class="commandline"> |
| 2676 |
<a class="external" href="commands.html#set">set</a> {Programmable Device |
| 2677 |
input callback} "my_input_proc" |
| 2678 |
</div> |
| 2679 |
<p> |
| 2680 |
connects the "IN instruction" event with your previously declared |
| 2681 |
"my_input_proc" callback. |
| 2682 |
</p> |
| 2683 |
|
| 2684 |
<h3><a id="sdcdb">9.6 SDCC Debugger</a></h3> |
| 2685 |
|
| 2686 |
<p> |
| 2687 |
openMSX includes the SDCC Debugger called sdcdb, a Tcl script that mimics GDB (GNU Debugger) and allows you to inspect programs compiled with the Small Device C Compiler (SDCC) from the console. You just need to compile your SDCC code with the <code>-debug</code> flag to create a CDB file with symbols and their respective addresses and then call <code>sdcdb open <directory></code> where the CDB file and source code are. Now you can inspect the program while it executes. For instance, to create a breakpoint at file <code>main.c</code>, line 155 from your source code, you can type: |
| 2688 |
</p> |
| 2689 |
|
| 2690 |
<div class="commandline"> |
| 2691 |
sdcdb break main.c:155 |
| 2692 |
</div> |
| 2693 |
|
| 2694 |
<p>A SDCDB breakpoint is a regular breakpoint and it can be listed with the <code>debug breakpoint list</code> command. When a breakpoint is triggered, you can inspect the source code around it with command <code>sdcdb info</code>. There are two commands that executes code step by step. The first is <code>sdcdb step</code>, which executes C code line by line and goes inside function calls. It is equivalent to the <code>step_in</code> command from the console. The second is <code>sdcdb next</code>, which executes C code line by line but doesn't go inside function calls. It is equivalent to the <code>step_over</code> command from the console. The useful <code>sdcdb laddress <address></code> will display source code under the given memory address since sdcdb is aware of the program's source code, like GDB. You can type <code>help sdcdb</code> for more details or check out the comments in <code>sdcdb.tcl</code> script for more examples.</p> |
| 2695 |
|
| 2696 |
<h2><a id="contact">10. Contact Info</a></h2> |
| 2697 |
|
| 2698 |
<p> |
| 2699 |
Because openMSX is still in heavy development, feedback and bug reports are very |
| 2700 |
welcome! |
| 2701 |
</p> |
| 2702 |
|
| 2703 |
<p> |
| 2704 |
If you encounter problems, you have several options: |
| 2705 |
</p> |
| 2706 |
|
| 2707 |
<ol> |
| 2708 |
<li> |
| 2709 |
Go to our IRC channel: <a class="external" |
| 2710 |
href="ircs://irc.libera.chat:6697/#openMSX"><code>#openMSX</code> on |
| 2711 |
<code>libera.chat</code></a> |
| 2712 |
and ask your question there. Also reachable via <a class="external" |
| 2713 |
href="https://web.libera.chat/#openMSX">webchat</a>! If you don't get a reply |
| 2714 |
immediately, please stick around for a while, or use one of the other contact |
| 2715 |
options. The majority of the developers lives in time zone GMT+1. You may get |
| 2716 |
no response if you contact them in the middle of the night... </li> |
| 2717 |
<li> |
| 2718 |
Post a message on <a class="external" |
| 2719 |
href="http://www.msx.org/forum/semi-msx-talk/openmsx">the openMSX forum on |
| 2720 |
MRC</a>. |
| 2721 |
</li> |
| 2722 |
<li> |
| 2723 |
Create a new issue in the |
| 2724 |
<a class="external" href="https://github.com/openMSX/openMSX/issues">openMSX |
| 2725 |
issue tracker</a> |
| 2726 |
on GitHub. |
| 2727 |
You need a (free) log-in on GitHub to get access. |
| 2728 |
</li> |
| 2729 |
<li> |
| 2730 |
Contact us and other users via one of the mailing lists. If you're a regular |
| 2731 |
user and want to discuss openMSX and possible problems, join our |
| 2732 |
<code>openmsx-user</code> mailing list. |
| 2733 |
If you want to address the openMSX developers directly, post a message to the |
| 2734 |
<code>openmsx-devel</code> mailing list. |
| 2735 |
More info on the |
| 2736 |
<a class="external" href="https://sourceforge.net/p/openmsx/mailman">openMSX mailing lists</a>, |
| 2737 |
including an archive of old messages, can be found at SourceForge. |
| 2738 |
</li> |
| 2739 |
</ol> |
| 2740 |
|
| 2741 |
<p> |
| 2742 |
In any case, try to give as much information as possible when you describe your |
| 2743 |
bug or request. |
| 2744 |
</p> |
| 2745 |
|
| 2746 |
</body> |
| 2747 |
</html> |