e8555c89 Andy McCall 1 month ago 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 > </ title >
9
</ head >
10
11
< body >
12
13
< h1 > </ h1 >
14
15
< h2 > </ h2 >
16
17
< ol class = " toc " >
18
< li > < a class = " internal " href = " #intro" > </ a >
19
< ol class = " toc " >
20
< li > < a class = " internal " href = " #newver" > </ a > </ li >
21
< li > < a class = " internal " href = " #purpose" > </ a > </ li >
22
< li > < a class = " internal " href = " #history" > </ a > </ li >
23
< li > < a class = " internal " href = " #terms" > </ a > </ li >
24
</ ol >
25
</ li >
26
< li > < a class = " internal " href = " #starting" > </ a >
27
< ol class = " toc " >
28
< li > < a class = " internal " href = " #machines" > </ a > </ li >
29
< li > < a class = " internal " href = " #extensions" > </ a > </ li >
30
< li > < a class = " internal " href = " #otheroptions" > </ a > </ li >
31
</ ol >
32
</ li >
33
< li > < a class = " internal " href = " #controlling" > </ a >
34
< ol class = " toc " >
35
< li > < a class = " internal " href = " #console" > </ a > </ li >
36
< li > < a class = " internal " href = " #importantconsole" > </ a > </ li >
37
< li > < a class = " internal " href = " #settings" > </ a > </ li >
38
< li > < a class = " internal " href = " #plug" > </ a > </ li >
39
</ ol >
40
</ li >
41
< li > < a class = " internal " href = " #gui" > </ a >
42
< ol class = " toc " >
43
< li > < a class = " internal " href = " #guioverview" > </ a > </ li >
44
< li > < a class = " internal " href = " #guimainmenu" > </ a > </ li >
45
< li > < a class = " internal " href = " #guiother" > </ a > </ li >
46
< li > < a class = " internal " href = " #guiadvanced" > </ a >
47
< ol class = " toc " >
48
< li > < a class = " internal " href = " #guiadvanced_tips" > </ a > </ li >
49
</ ol >
50
</ li >
51
</ ol >
52
</ li >
53
< li > < a class = " internal " href = " #media" > </ a >
54
< ol class = " toc " >
55
< li > < a class = " internal " href = " #roms" > </ a > </ li >
56
< li > < a class = " internal " href = " #disks" > </ a >
57
< ol class = " toc " >
58
< li > < a class = " internal " href = " #diskimages" > </ a > </ li >
59
< li > < a class = " internal " href = " #dirasdisk" > </ a > </ li >
60
< li > < a class = " internal " href = " #realdisks" > </ a > </ li >
61
< li > < a class = " internal " href = " #diskmanagement" > </ a > </ li >
62
</ ol >
63
</ li >
64
< li > < a class = " internal " href = " #tape" > </ a >
65
< ol class = " toc " >
66
< li > < a class = " internal " href = " #cas" > </ a > </ li >
67
</ ol >
68
</ li >
69
70
< li > < a class = " internal " href = " #harddisks" > </ a >
71
< ol class = " toc " >
72
< li > < a class = " internal " href = " #ide" > </ a > </ li >
73
< li > < a class = " internal " href = " #beeride" > </ a > </ li >
74
< li > < a class = " internal " href = " #scsi" > </ a > </ li >
75
< li > < a class = " internal " href = " #sd" > </ a > </ li >
76
</ ol >
77
</ li >
78
79
< li > < a class = " internal " href = " #laserdisc" > </ a > </ li >
80
</ ol >
81
</ li >
82
83
< li > < a class = " internal " href = " #input" > </ a >
84
< ol class = " toc " >
85
< li > < a class = " internal " href = " #keyboard" > </ a >
86
< ol class = " toc " >
87
< li > < a class = " internal " href = " #msxkeymapping" > </ a > </ li >
88
< li > < a class = " internal " href = " #cvkeymapping" > </ a > </ li >
89
< li > < a class = " internal " href = " #emukeymapping" > </ a > </ li >
90
< li > < a class = " internal " href = " #keyboardlayouts" > </ a > </ li >
91
</ ol >
92
</ li >
93
< li > < a class = " internal " href = " #joystick" > </ a > </ li >
94
< li > < a class = " internal " href = " #mouse" > </ a > </ li >
95
< li > < a class = " internal " href = " #arkanoidpad" > </ a > </ li >
96
< li > < a class = " internal " href = " #trackball" > </ a > </ li >
97
< li > < a class = " internal " href = " #touchpad" > </ a > </ li >
98
< li > < a class = " internal " href = " #magickey" > </ a > </ li >
99
< li > < a class = " internal " href = " #ninjatap" > </ a > </ li >
100
< li > < a class = " internal " href = " #tetris2dongle" > </ a > </ li >
101
< li > < a class = " internal " href = " #msxpaddle" > </ a > </ li >
102
< li > < a class = " internal " href = " #circuitdesignerdongle" > </ a > </ li >
103
</ ol >
104
</ li >
105
106
< li > < a class = " internal " href = " #video" > </ a >
107
< ol class = " toc " >
108
< li > < a class = " internal " href = " #scalers" > </ a > </ li >
109
< li > < a class = " internal " href = " #gamma" > </ a > </ li >
110
< li > < a class = " internal " href = " #videoeffects" > </ a > </ li >
111
< li > < a class = " internal " href = " #accuracy" > </ a > </ li >
112
< li > < a class = " internal " href = " #gfx9000" > </ a > </ li >
113
< li > < a class = " internal " href = " #recording" > </ a > </ li >
114
</ ol >
115
</ li >
116
117
< li > < a class = " internal " href = " #audio" > </ a >
118
< ol class = " toc " >
119
< li > < a class = " internal " href = " #audiosettings" > </ a > </ li >
120
< li > < a class = " internal " href = " #midi" > </ a > </ li >
121
< li > < a class = " internal " href = " #soundlogger" > </ a > </ li >
122
</ ol >
123
</ li >
124
125
< li > < a class = " internal " href = " #usefulextras" > </ a >
126
< ol class = " toc " >
127
< li > < a class = " internal " href = " #savestate" > </ a > </ li >
128
< li > < a class = " internal " href = " #reverse" > </ a > </ li >
129
< li > < a class = " internal " href = " #trainer" > </ a > </ li >
130
< li > < a class = " internal " href = " #debugdevice" > </ a >
131
< ol class = " toc " >
132
< li > < a class = " internal " href = " #debugdeviceenable" > </ a > </ li >
133
< li > < a class = " internal " href = " #debugdeviceports" > </ a > </ li >
134
< li > < a class = " internal " href = " #debugdevicemode1" > </ a > </ li >
135
< li > < a class = " internal " href = " #debugdevicemode2" > </ a > </ li >
136
</ ol >
137
</ li >
138
< li > < a class = " internal " href = " #programmabledevice" > </ a >
139
< ol class = " toc " >
140
< li > < a class = " internal " href = " #programmabledeviceenable" > </ a > </ li >
141
< li > < a class = " internal " href = " #programmabledeviceports" > </ a > </ li >
142
</ ol >
143
</ li >
144
< li > < a class = " internal " href = " #sdcdb" > </ a > </ li >
145
</ ol >
146
</ li >
147
< li > < a class = " internal " href = " #contact" > </ a > </ li >
148
</ ol >
149
150
151
< h2 > < a id = " intro " > </ a > </ h2 >
152
153
< h3 > < a id = " newver " > </ 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/" > </ a >
159
</ p >
160
161
< h3 > < a id = " 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/" > </ 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 > </ 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 " > </ 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" > </ a >
199
</ p >
200
201
< h3 > < a id = " 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 > </ dt >
209
< dd > </ dd >
210
< dd > </ dd >
211
< dt > </ dt >
212
< dd > </ dd >
213
< dd > </ dd >
214
< dd > </ dd >
215
< dt > </ dt >
216
< dd > </ dd >
217
< dd > </ dd >
218
< dd > </ dd >
219
< dd > </ dd >
220
< dt > </ dt >
221
< dd > </ dd >
222
< dd > </ dd >
223
< dd > </ dd >
224
< dt > </ dt >
225
< dd > </ dd >
226
< dd > </ dd >
227
< dd > </ dd >
228
</ dl >
229
230
< h2 > < a id = " starting " > </ 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 " > </ 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" > </ a > </ code >
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" > </ a > </ code >
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 " >
254
bar & rarr; & rarr; </ span >
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 > </ code >
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" > </ a > </ code >
274
in the < a class = " internal " href = " #console" > </ a >
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" > </ a >
282
You can always use < span class = " menu-reference " > & rarr;
283
& rarr; </ span >
284
installed.
285
</ p >
286
287
< p >
288
If you have saved a setup earlier (using the GUI via < span class = " menu-reference " >
289
& rarr; & rarr; </ span > < code > < a class = " external "
290
href = " commands.html#store_setup" > </ a > </ code > < span class = " menu-reference " >
291
bar & rarr; & rarr; </ span >
292
here you can use the command line (via the < code > </ code >
293
option) or the console (via the < code > < a class = " external "
294
href = " commands.html#setup" > </ a > </ code >
295
</ p >
296
297
< h3 > < a id = " 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" > </ a >
304
details.
305
</ p >
306
307
< p >
308
Using the GUI, use the < span class = " menu-reference " > & rarr;
309
Media</ span >
310
put the extension into, or directly select the < span class = " menu-reference " > </ span >
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" > </ a >
319
< code > </ code >
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" > </ a > </ code >
328
time. You can also use something like < code > </ code >
329
cartridge slot B.
330
</ p >
331
332
< p >
333
If you look in the < code > </ code >
334
console, type the TAB key with the < code > </ code >
335
you will see all the extensions known to openMSX. For example < code >
336
mbstereo</ code >
337
speaker and MSX-AUDIO on the right speaker.
338
</ p >
339
340
< h3 > < a id = " otheroptions " > </ 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 " > </ div >
347
348
< h2 > < a id = " controlling " > </ a > </ h2 >
349
350
< h3 > < a id = " console " > </ 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 > </ 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" > </ a >
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 > </ code > </ a >
373
gives a list of commands. Using PageUp you can see all of them. If you type
374
< code > </ code >
375
manual describes a few important commands; a full list can be found in the < a
376
class = " external " href = " commands.html" > </ a >
377
console can be used to < a class = " internal " href = " #disks" >
378
images</ a > < a class = " internal " href = " #joystick" > </ a > < a
379
class = " internal " href = " #mouse" > </ a > < a class = " internal "
380
href = " #settings" > </ a >
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 >
394
It also supports copy/paste. Some other controls may be less obvious: </ p >
395
396
< table >
397
< tr > < th > </ th > < th > </ th > </ tr >
398
< tr > < td > </ td > < td > </ td > </ tr >
399
< tr > < td > </ td > < td > </ td > </ tr >
400
< tr > < td > </ td > < td > </ td > </ tr >
401
< tr > < td > </ td > < td > </ td > </ tr >
402
</ table >
403
404
< h3 > < a id = " importantconsole " > </ a > </ h3 >
405
406
< p >
407
You can reset your MSX with the console command < code > < a class = " external "
408
href = " commands.html#reset" > </ a > </ code >
409
< code > < a class = " external " href = " commands.html#exit" > </ a > </ code >
410
explained in the previous chapter, you can change machines with the < code > < a
411
class = " external " href = " commands.html#machine" > </ a > </ code >
412
you can insert extensions with the < code > < a class = " external "
413
href = " commands.html#ext" > </ a > </ code >
414
list of possible extension names). Remove extensions with the < code > < a
415
class = " external "
416
href = " commands.html#remove_extension" > </ a > </ code >
417
get a list of the currently inserted extensions with the < code > < a
418
class = " external "
419
href = " commands.html#list_extensions" > </ a > </ code >
420
commands will be discussed later on in this manual.
421
</ p >
422
423
< h3 > < a id = " 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 " > & rarr; </ span >
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 " > & rarr; </ span >
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" > </ a > </ code >
438
use it to set the current < a class = " internal " href = " #scalers" > </ a >
439
< code > </ code > < code > < a class = " external "
440
href = " commands.html#scale_algorithm" > </ a > </ code >
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" > </ a > </ code >
444
command (an example is the default key binding of F11 to < code >
445
fullscreen</ code >
446
also be found in the < a class = " external " href = " commands.html" >
447
Reference</ a >
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" > </ a > </ code >
459
which has the speed percentage as parameter. So, typing < code >
460
speed 120</ code >
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 " > & rarr; & rarr; & rarr; </ 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 > < a class = " external "
471
href = " commands.html#firmwareswitch" > </ a > </ code >
472
currently running machine has a firmware switch, a toggle option will show up in
473
the < span class = " menu-reference " > & rarr; </ span >
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 > < a class = " external "
480
href = " commands.html#fullspeedwhenloading" > </ a > </ code >
481
or from the GUI at < span class = " menu-reference " > & rarr;
482
& rarr; & rarr; </ span >
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" > </ a > </ code >
493
up, alternative settings files can be loaded by using the < code > </ code >
494
command-line option. You can also use the < code > < a class = " external "
495
href = " commands.html#load_settings" > </ a > </ code >
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" > </ a >
499
automatically save your settings on exit (whichever way they were changed).
500
</ p >
501
502
< h3 > < a id = " plug " > </ a > </ h3 >
503
504
< p >
505
The < span class = " menu-reference " > & rarr; </ span >
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" > </ a > < a class = " internal "
515
href = " #mouse" > </ a >
516
</ p >
517
518
< p >
519
In the console, you can use the command < code > < a class = " external "
520
href = " commands.html#plugunplug" > </ a > </ code >
521
< code > < a class = " external " href = " commands.html#plugunplug" > </ a > </ code >
522
without any parameters will show a list of connectors and what pluggables are
523
plugged into them. Using < code > </ code >
524
plugged into [connector]. It will come as no surprise that the command < code >
525
[connector] [pluggable]</ code >
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 " > </ a > </ h2 >
541
542
< h3 > < a id = " guioverview " > </ 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" >
547
library</ a >
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 " > & rarr; & rarr;
557
guide</ span >
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" > </ a >
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 " > </ 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 > </ dt >
599
< dd > </ dd >
600
< dd > </ dd >
601
< dd > </ dd >
602
< dt > </ dt >
603
< dd >
604
tapes, laserdiscs, ...</ dd >
605
< dt > </ dt >
606
< dd >
607
printers, joysticks, mice, dongles, MIDI equipment, ...</ dd >
608
< dt > </ dt >
609
< dd > </ dd >
610
< dt > </ dt >
611
< dd >
612
copying and pasting, audio and video capture, disk manipulation/management,
613
trainers and cheats, audio chip tools and gadgets, etc..</ dd >
614
< dt > </ dt >
615
< dd >
616
Speed, Input, the GUI and Misc settings.</ dd >
617
< dd > </ dd >
618
< dt > </ dt >
619
< dd >
620
functionality from the old, standalone openMSX debugger has been included.</ dd >
621
< dt > </ dt >
622
< dd > </ 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 " > </ 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 > </ dt >
642
< dd > < img src = " reverse_bar.png" width = " 245" height = " 39" alt = " Main menu bar." > </ dd >
643
< dd > </ dd >
644
< dd > </ dd >
645
< dd > < span class = " menu-reference " > & rarr;
646
move</ span > < span class = " menu-reference " > & rarr;
647
Hide title</ span >
648
window.</ dd >
649
< dd > < span class = " menu-reference " > & rarr;
650
state & rarr; & rarr; </ span > </ dd >
651
< dd > </ dd >
652
< dt > </ dt >
653
< dd > < img src = " osd_icons.png" width = " 516" height = " 57" alt = " Main menu bar." > </ dd >
654
< dd > </ dd >
655
< dd > </ dd >
656
< dd > </ dd >
657
< dd > < span class = " menu-reference " > & rarr;
658
Settings & rarr; & rarr; </ span > </ dd >
659
< dd >
660
and drag the icons to a new location, possibly outside the main openMSX window,
661
possibly docked to another window.</ dd >
662
< dt > </ dt >
663
< dd > < img src = " status_bar.png" width = " 739" height = " 29" alt = " Main menu bar." > </ dd >
664
< dd >
665
information about the currently running machine and emulation performance.</ dd >
666
< dd > < span class = " menu-reference " >
667
menu bar & rarr; & rarr; & rarr; </ span > </ dd >
668
</ dl >
669
670
< h3 > < a id = " guiadvanced " > </ 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 > </ li >
693
< li > </ li >
694
< li > </ 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 " > </ 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 > </ li >
710
< li > </ 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 > </ li >
725
< li > </ li >
726
< li > </ li >
727
< li > </ li >
728
< li > </ li >
729
< li > </ li >
730
</ ul >
731
732
Tips if you stil end up to have many (overlapping) windows:
733
< ul >
734
< li > </ li >
735
< li > </ li >
736
</ ul >
737
738
739
740
741
742
743
< h2 > < a id = " 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 " > & rarr;
748
Media</ span >
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 > </ code >
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 " > </ 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 " > & rarr; </ span >
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 > </ h4 >
784
785
< p >
786
Using the command line, suppose you want to run the ROM file
787
< code > </ code >
788
</ p >
789
< div class = " commandline " > </ div >
790
< p >
791
and the emulated MSX will run the game. (Of course,
792
in this case, the file < code > </ code >
793
You can also explicitly indicate that the thing is a ROM image like this:
794
</ p >
795
< div class = " commandline " > </ div >
796
< p >
797
This lets openMSX know that the file < code > </ code >
798
cartridge and that openMSX should insert it in the first available free
799
cartridge slot. You can also use < code > </ code >
800
cartridge slot A.
801
</ p >
802
< p >
803
You can also explicitly specify the mapper type to use (< code > </ code >
804
for instance) with the < code > </ code >
805
</ p >
806
< div class = " commandline " > </ 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 " > </ div >
823
< p >
824
As with the < code > </ code > < code > </ code >
825
command line must follow the ROM file it applies to directly. You can also use
826
multiple < code > </ code >
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" > </ a > </ code > < a
833
class = " internal " href = " #console" > </ a >
834
powerful.
835
</ p >
836
837
< h3 > < a id = " disks " > </ a > </ h3 >
838
839
< h4 > < a id = " diskimages " > </ 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 > </ h5 >
860
861
< p >
862
To specify disk images on the command line, you can type:
863
</ p >
864
< div class = " commandline " > </ 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 " > </ 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" > </ a > & lt; & gt;
876
</ div >
877
< p >
878
in the < a class = " internal " href = " #console" > </ a >
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" > </ a >
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 " > </ div >
892
< p >
893
On the command line, the < code > </ code >
894
it applies to. You can also use multiple < code > </ code >
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" > </ a >
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 " > </ 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" > </ a >
933
directory on the host system < em > </ em >
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" >
936
the documentation</ a >
937
</ p >
938
< p >
939
< em > </ em >
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 " > </ 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 " > </ 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 " >
967
bar & rarr; & rarr; </ span >
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" > </ a >
979
</ p >
980
981
< h3 > < a id = " tape " > </ 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 " > & rarr; & rarr;
996
Deck</ span >
997
you to insert a cassette tape image.
998
</ p >
999
1000
< p > < a class = " internal " href = " #console" > </ a >
1001
</ p >
1002
< div class = " commandline " >
1003
< a class = " external " href = " commands.html#cassetteplayer" > </ a > & lt; & gt;
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 > </ code > </ li >
1020
< li > < code > </ code > </ li >
1021
< li > < code > & lt; & gt; </ code > </ li >
1022
< li > < code > </ code > </ li >
1023
< li > < code > </ code > </ li >
1024
< li > < code > </ code > </ 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 > </ 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 " > </ 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 " > & rarr; & rarr; & rarr; </ span > < a class = " external " href = " commands.html#fullspeedwhenloading" > </ 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 " > & rarr; & rarr; & rarr; & rarr; </ span > < a class = " external " href = " commands.html#autoruncassettes" > </ a >
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 " > </ 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 > </ code >
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 > </ code >
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" > </ a > </ code >
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" > </ a >
1100
</ p >
1101
1102
< p >
1103
In the GUI under < span class = " menu-reference " > & rarr; </ 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 " >
1109
bar & rarr; </ span > < code > < a class = " external " href = " commands.html#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 " > </ 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" > </ a > < code > < a class = " external "
1121
href = " commands.html#disk" > </ a > </ code >
1122
</ p >
1123
< div class = " commandline " >
1124
< a class = " external " href = " commands.html#hd" > </ a > & lt; & gt;
1125
</ div >
1126
1127
< p > </ p >
1128
1129
< h4 > < a id = " 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" >
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" >
1149
site</ a > < a class = " external "
1150
href = " https://www.msx.org/forum/semi-msx-talk/emulation/how-get-sunrise-ide-working-openmsx" > </ a >
1151
< a class = " external "
1152
href = " https://www.msx.org/forum/semi-msx-talk/emulation/openmsx-harddisk-emulation" > </ 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" > </ a > </ code >
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" > </ a >
1164
</ p >
1165
< div class = " commandline " >
1166
set < a class = " external " href = " commands.html#power" > </ a > < br />
1167
< a class = " external " href = " diskmanipulator.html" > </ a > < a class = " external " href = " diskmanipulator.html#create" > </ a > < br />
1168
< a class = " external " href = " commands.html#hd" > </ a > < br />
1169
< a class = " external " href = " diskmanipulator.html" > </ a > < a class = " external " href = " diskmanipulator.html#import" > </ a > < br />
1170
< a class = " external " href = " diskmanipulator.html" > </ a > < a class = " external " href = " diskmanipulator.html#import" > </ a > < br />
1171
< a class = " external " href = " diskmanipulator.html" > </ a > < a class = " external " href = " diskmanipulator.html#import" > </ a > < br />
1172
set < a class = " external " href = " commands.html#power" > </ a >
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 > </ code >
1179
< code > < a class = " external " href = " commands.html#cd" > </ a > </ code >
1180
command, all similar to the aforementioned < code > < a class = " external "
1181
href = " commands.html#hd" > </ a > </ code > < code > < a class = " external "
1182
href = " commands.html#disk" > </ a > </ code >
1183
</ p >
1184
1185
< h4 > < a id = " beeride " > </ 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" > </ a >
1199
matching command-line parameter < code > </ code >
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 > </ code >
1210
</ p >
1211
1212
< p >
1213
With the 1.9RC1 firmware, you can use < code > < a class = " external "
1214
href = " diskmanipulator.html" > </ a > </ code >
1215
image and import from and export to them. To get started, partition the default
1216
drive with < code > </ code >
1217
Then import MSX-DOS system files onto the first partition using
1218
< code > & lt; & gt; </ code >
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 " > </ 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 > </ p >
1243
1244
< p >
1245
To change the disk image of the LS-120 device, use the < code > </ code >
1246
drive A) command, exactly the same as the < a class = " external "
1247
href = " commands.html#hd" > </ a >
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 > </ code >
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 > </ code >
1257
which can be found on < a class = " external "
1258
href = " http://www.msxnet.org/gtinter/nogame-e.htm" > </ 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 > </ code >
1262
want to use < code > </ code >
1263
cartridge). After this, the MSX will boot from the SRAM disk. Use the
1264
< code > </ code > < code > </ code >
1265
to format the drive (use a physical format, for now). Use < code > </ code >
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" >
1272
Otten's Page</ a > < a class = " external "
1273
href = " http://faq.msxnet.org/scsi.html" > </ a >
1274
also contain manuals for the Novaxis ROM. Initialisation is done with the
1275
< code > </ code > < a class = " external "
1276
href = " https://web.archive.org/web/20200315110709/http://members.chello.nl/m.delorme/" > </ a >
1277
</ p >
1278
1279
< h4 > < a id = " 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 > </ 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" > </ a >
1314
parameters < code > </ code > < code > </ code >
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 > </ code >
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/" >
1324
Cartridge Shop</ a >
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" > </ a > </ code >
1331
< code > </ code >
1332
is explained above < a class = " internal " href = " #ide" >
1333
section</ a >
1334
</ p >
1335
1336
< h3 > < a id = " laserdisc " > </ 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 " >
1348
menu bar & rarr; & rarr; </ span > < a
1349
class = " internal " href = " #console" > </ a > < code > < a class = " external " href = " commands.html#laserdiscplayer" > </ a > & lt; & gt; </ 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" > </ 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 > < a class = " external "
1373
href = " commands.html#fullspeedwhenloading" > </ a > </ 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 " > </ a > </ h2 >
1379
1380
< h3 > < a id = " keyboard " > </ a > </ h3 >
1381
1382
< a id = " keymapping " > </ a >
1383
< h4 > < a id = " msxkeymapping " > </ 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 > </ th > < th > </ th > < th > </ th > </ tr >
1392
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1393
< tr > < td > < a class = " external " href = " commands.html#kbd_deadkey1_host_key" > </ a > </ td > < td > </ td > < td > </ td > </ tr >
1394
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1395
< tr > < td > < a class = " external " href = " commands.html#kbd_code_kana_host_key" > </ a > </ td > < td > </ td > < td > </ td > </ tr >
1396
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1397
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1398
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1399
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1400
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1401
</ table >
1402
1403
< h4 > < a id = " cvkeymapping " > </ a > </ h4 >
1404
1405
< p > </ p >
1406
1407
< table >
1408
< tr > < th > </ th > < th > </ th > < th > </ th > </ tr >
1409
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1410
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1411
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1412
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1413
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1414
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1415
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1416
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1417
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1418
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1419
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1420
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1421
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1422
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1423
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1424
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1425
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1426
< tr > < td > </ td > < td > </ td > < td > </ 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 " > </ 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 > </ code > </ a >
1439
the < a class = " internal " href = " #console" > </ a >
1440
bindings are saved together with the settings. This subsection lists the
1441
default key mapping.
1442
</ p >
1443
1444
< table >
1445
< tr > < th > </ th > < th > </ th > < th > </ th > </ tr >
1446
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1447
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1448
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1449
< tr > < td > </ td > < td > </ td > < td > < a class = " external " href = " commands.html#screenshot" > </ a > </ td > </ tr >
1450
< tr > < td > </ td > < td > </ td > < td > < a class = " external " href = " commands.html#reverse" > </ a > </ td > </ tr >
1451
< tr > < td > </ td > < td > </ td > < td > < a class = " external " href = " commands.html#reverse" > </ a > </ td > </ tr >
1452
< tr > < td > </ td > < td > </ td > < td > < a class = " external " href = " commands.html#fastforward" > </ a > </ td > </ tr >
1453
< tr > < td > </ td > < td > </ td > < td > < a class = " external " href = " commands.html#console" > </ a > </ td > </ tr >
1454
< tr > < td > </ td > < td > </ td > < td > < a class = " external " href = " commands.html#fullscreen" > </ a > </ td > </ tr >
1455
< tr > < td > </ td > < td > </ td > < td > < a class = " external " href = " commands.html#mute" > </ a > </ td > </ tr >
1456
< tr > < td > </ td > < td > </ td > < td > < a class = " external " href = " commands.html#savestate" > </ a > </ td > </ tr >
1457
< tr > < td > </ td > < td > </ td > < td > < a class = " external " href = " commands.html#savestate" > </ a > </ td > </ tr >
1458
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1459
< tr > < td > </ td > < td > </ td > < td > </ td > </ tr >
1460
</ table >
1461
1462
1463
1464
1465
1466
< p >
1467
Note that Mac users must use < code > </ code >
1468
(Apple logo) key. On PC's use < code > </ code >
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 " > </ 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" > </ a >
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" >
1503
mode</ a > < a class = " external "
1504
href = " commands.html#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" > </ a >
1507
an alternative host key for CODE/KANA) and < a class = " external "
1508
href = " commands.html#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 " >
1514
bar & rarr; & rarr; & rarr; </ span >
1515
</ p >
1516
1517
< h3 > < a id = " 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 > </ code >
1522
< code > </ code > < code > </ code > < code > </ code >
1523
</ p >
1524
1525
< p >
1526
See the < a class = " internal " href = " #plug" >
1527
devices</ a >
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 " > & rarr;
1534
Settings & rarr; & rarr; </ span >
1535
in the console with the < a class = " external "
1536
href = " commands.html#msxjoystickN_config" > & lt; & gt; & lt; & gt; </ 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" > </ a > </ code >
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" > </ a >
1564
unfortunately, such mappings are not configurable via the GUI menu.
1565
</ p >
1566
< h3 > < a id = " mouse " > </ a > </ h3 >
1567
1568
< p >
1569
To connect a mouse, you can also use the < span class = " menu-reference " >
1570
bar & rarr; </ span > < code > < a
1571
class = " external " href = " commands.html#plugunplug" > </ a > </ code > < code > </ 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 > < a
1580
class = " external " href = " commands.html#grabinput" > </ a > </ 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" > </ a > </ code >
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" > </ a > </ code >
1589
mentioned above. You can also toggle the setting via < span
1590
class = " menu-reference " > & rarr; & rarr; & rarr;
1591
input</ span >
1592
</ p >
1593
1594
< h3 > < a id = " arkanoidpad " > </ 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 " > & rarr; </ span >
1601
the console with < code > < a class = " external " href = " commands.html#plugunplug" > </ a >
1602
</ code >
1603
</ p >
1604
1605
< h3 > < a id = " 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" > </ a > </ 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 " > </ 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" > </ a > </ 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" > </ a >
1642
setting for how to adjust this.
1643
</ p >
1644
1645
< h3 > < a id = " magickey " > </ 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" > </ a >
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 > </ dt >
1661
< dd > </ dd >
1662
< dt > </ dt >
1663
< dd >
1664
"Actual Battle" on the menu screen and pressing ESC and SELECT.</ dd >
1665
< dt > </ dt >
1666
< dd > </ dd >
1667
</ dl >
1668
1669
< h3 > < a id = " ninjatap " > </ 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" > </ a > </ code >
1676
</ p >
1677
1678
1679
< h3 > < a id = " tetris2dongle " > </ 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" > </ a >
1685
</ code >
1686
</ p >
1687
1688
< h3 > < a id = " msxpaddle " > </ 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" > </ a >
1695
joyporta paddle</ code >
1696
</ p >
1697
1698
< h3 > < a id = " circuitdesignerrddongle " > </ 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" > </ a >
1704
</ code >
1705
</ p >
1706
1707
< h2 > < a id = " 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" > </ 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 " > & rarr; & rarr; </ span >
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" > </ a > </ code >
1730
</ p >
1731
1732
< h3 > < a id = " scalers " > </ a > </ h3 >
1733
1734
< p >
1735
Most MSX screen modes are only 256& times;
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& times;
1739
window, for 3 to a 960& times;
1740
1280& times; < code > < a
1741
class = " external " href = " commands.html#scale_factor" > </ a > </ code >
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" > </ a > </ code >
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 > </ dt >
1762
< dd >
1763
This algorithm simply expands each MSX pixel to a square of
1764
(scale_factor)& times;
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/" > </ 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" > </ 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 > </ 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& times;
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" >
1797
Grille</ a >
1798
control the effect with the < code > < a class = " external "
1799
href = " commands.html#blur" > </ a > </ code >
1800
scan lines.
1801
</ dd >
1802
1803
< dt > </ 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/" >
1815
site</ a >
1816
</ p >
1817
1818
< h3 > < a id = " gamma " > </ 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" > </ a > </ code >
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" >
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 " > </ 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" > </ 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" > </ a > </ code >
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" > </ 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" > </ 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 > </ code > < code > </ code > < code > </ code >
1886
</ dd >
1887
1888
< dt > < code > < a class = " external " href = " commands.html#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" > </ 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 > </ code > < code > </ code >
1900
</ dd >
1901
1902
< dt > < code > < a class = " external " href = " commands.html#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" > </ a > </ code >
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" > </ 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" > </ 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 > < code > < a class = " external "
1921
href = " commands.html#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 > </ code > </ li >
1926
< li > < code > </ code > </ li >
1927
</ ul >
1928
</ dd >
1929
1930
</ dl >
1931
1932
< h3 > < a id = " accuracy " > </ a > </ h3 >
1933
1934
< p >
1935
An advanced setting (which you can find under < span class = " menu-reference " >
1936
menu bar & rarr; & rarr; & rarr; </ span >
1937
(the < code > < a class = " external "
1938
href = " commands.html#accuracy" > </ a > </ code >
1939
the renderer is synchronised with the MSX video processor (VDP).
1940
There are three options:
1941
</ p >
1942
1943
< dl >
1944
< dt > </ 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 > </ 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 > </ 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 " > </ 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 >
1986
< a class = " external " href = " commands.html#videosource" > </ a > </ 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 " > & rarr; & rarr; & rarr;
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" > </ a > < a
2012
class = " external " href = " commands.html#videosource" > </ a > </ code > < br />
2013
< code > < a class = " external " href = " commands.html#cycle" > </ a > </ code >
2014
command that cycles through the options of the setting in the parameter.
2015
</ p >
2016
2017
< h3 > < a id = " 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& times;
2022
default, at 640& times; < code > </ code >
2023
960& times; < code > </ code >
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" > </ a >
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" > </ a > </ code >
2034
If you change the < code > < a class = " external "
2035
href = " commands.html#frequency" > </ a > </ code >
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" > </ a >
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 > </ code >
2048
no stereo devices are present at the time you enter the command. You can also
2049
force a mono recording with < code > </ code >
2050
</ p >
2051
2052
< p >
2053
In the GUI you can find the video recorder under < span
2054
class = " menu-reference " > & rarr; & rarr; & rarr;
2055
Audio/Video</ span >
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" > </ a > </ code >
2062
name, or you can use an additional parameter to specify a file. The command
2063
< code > < a class = " external " href = " commands.html#record" > </ a > </ code >
2064
stops recording and < code > < a class = " external "
2065
href = " commands.html#record" > </ a > </ code >
2066
the < code > </ code > < code > </ code >
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/" > </ a > < a
2077
class = " external " href = " http://www.mplayerhq.hu/" > </ a >
2078
(Linux/UNIX). For YouTube you may want to use the command < code > < a
2079
class = " external " href = " commands.html#record" > </ a > </ code >
2080
it will enable you to chop up your video in several parts and enables
2081
< code > </ code >
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" > </ a > </ code >
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" > </ a >
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" >
2095
chapter about this feature</ a >
2096
</ p >
2097
2098
< h2 > < a id = " audio " > </ a > </ h2 >
2099
2100
< h3 > < a id = " audiosettings " > </ a > </ h3 >
2101
2102
< p >
2103
Most audio related settings can be found under the < span
2104
class = " menu-reference " > & rarr; & rarr; </ span >
2105
</ p >
2106
2107
< p >
2108
There is a < code > < a class = " external "
2109
href = " commands.html#master_volume" > </ a > </ code >
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" > </ a > </ code >
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 " > & rarr; & rarr;
2124
Sound & rarr; </ span >
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 > < a
2130
class = " external " href = " commands.html#soundchip_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 > < a class = " external "
2139
href = " commands.html#soundchip_balance" > </ a > </ code >
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" > </ a >
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" > </ a > < a
2149
class = " external " href = " commands.html#psg_detune_frequency" > </ a >
2150
(both percent and frequency) settings.
2151
</ p >
2152
2153
< h3 > < a id = " midi " > </ a > </ h3 >
2154
2155
< p >
2156
Currently, openMSX supports the following MSX MIDI interfaces:
2157
</ p >
2158
< ul >
2159
< li > </ li >
2160
< li > </ li >
2161
< li > </ li >
2162
< li > </ li >
2163
< li > </ 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 " > & rarr; </ span >
2170
openMSX < a class = " internal " href = " #console" > </ a >
2171
</ p >
2172
2173
< h4 > </ 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 > </ code >
2180
virtual MIDI port for Mac MIDI software to connect to.
2181
</ p >
2182
2183
< p >
2184
For example, use the machine < code > </ code >
2185
< a class = " external " href = " https://sourceforge.net/projects/munt/" > </ a >
2186
synthesizer (MT-32 emulator) using < span class = " menu-reference " >
2187
& rarr; </ span > < code > < a
2188
class = " external " href = " commands.html#plugunplug" > </ a >
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 >
2194
msx-midi-out</ code >
2195
</ p >
2196
2197
< p >
2198
The < code > </ code >
2199
logs MIDI events to a file.
2200
</ p >
2201
< p >
2202
You can specify the file to log to using < code >
2203
< a class = " external "
2204
href = " commands.html#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 > </ code >
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" >
2216
forum thread</ a >
2217
< code > </ code >
2218
</ p >
2219
2220
< h4 > </ 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 > </ code >
2225
appropriate connector name for other devices). Analogous to the above mentioned
2226
outputs you can connect a < code > </ code >
2227
or < code > </ code >
2228
show up as separate pluggables. On macOS a < code > </ code >
2229
available as well.
2230
</ p >
2231
2232
< h3 > < a id = " soundlogger " > </ 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 " > & rarr; & rarr; & rarr;
2244
Audio/Video</ span >
2245
select < span class = " menu-reference " > </ span >
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" > </ a > </ code >
2251
will automatically choose a file name and save it in the < code > </ 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" > </ a > </ code >
2255
can toggle the recording status using < code > < a class = " external "
2256
href = " commands.html#soundlog" > </ a > </ code >
2257
you < code > < a class = " external " href = " commands.html#bind" > </ a > </ code >
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 " > & rarr; & rarr; & rarr;
2268
sound chip settings</ span >
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" > </ a > </ code >
2273
that in contrast to the < code > < a class = " external "
2274
href = " commands.html#soundlog" > </ a > </ code >
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 " > </ a > </ h2 >
2281
2282
< h3 > < a id = " savestate " > </ 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 " > & rarr;
2296
state</ span >
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" >
2302
section</ a > < a class = " external "
2303
href = " commands.html#savestate" > </ a >
2304
parameter < code > </ code >
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" > </ 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" > </ a > </ code >
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 " > </ 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" > </ a >
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" > </ a > </ code >
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 " > & rarr;
2356
& rarr; & rarr; </ span >
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 " > & rarr; & rarr;
2363
settings & rarr; </ span > < code > < a
2364
class = " external " href = " commands.html#reverse" > </ a > </ code >
2365
And if you don't want it to restart again anymore, uncheck the < span
2366
class = " menu-reference " > & rarr; & rarr;
2367
settings & rarr; </ span > < a class = " external "
2368
href = " commands.html#auto_enable_reverse" > </ 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 " > & rarr; & rarr;
2376
replay</ span > < code > < a class = " external "
2377
href = " commands.html#reverse" > </ a > </ code >
2378
also be loaded of course, with < span
2379
class = " menu-reference " > & rarr; & rarr;
2380
replay</ span > < code > < a class = " external "
2381
href = " commands.html#reverse" > </ a > </ code >
2382
</ p >
2383
2384
< h3 > < a id = " 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 " > & rarr; & rarr; </ span >
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" > </ a >
2398
use. As always, you could type: < code > < a class = " external "
2399
href = " commands.html#trainer" > </ a > </ code >
2400
</ p >
2401
2402
< p >
2403
Suppose you want to cheat on Metal Gear. Then it would be useful to type:
2404
< code > </ code > < code >
2405
Gear</ code >
2406
the Metal Gear trainer. You can activate them by typing e.g.: < code >
2407
Metal\ Gear 1 2 3 4</ code >
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 > </ code >
2411
to activate all cheats you can simply type: < code >
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 " > </ 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" > </ a > </ code >
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 " >
2437
bar & rarr; </ span >
2438
</ p >
2439
2440
< h4 > < a id = " debugdeviceenable " > </ a > </ h4 >
2441
2442
< p >
2443
To enable the debug device, insert the < code > </ code >
2444
do this when starting openMSX, simply add < code > </ code >
2445
openMSX command line. If openMSX is already running, you can use the
2446
< code > < a class = " external " href = " commands.html#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" > </ a > </ code >
2453
file name to write the debug output to.
2454
</ p >
2455
2456
< h4 > < a id = " debugdeviceports " > </ 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 > </ th > < th > </ th > </ tr >
2465
< tr > < td > </ td > < td > </ td > </ tr >
2466
< tr > < td > </ td > < td > </ td > </ tr >
2467
< tr > < td > </ td > < td > </ td > </ tr >
2468
< tr > < td > </ td > < td > </ 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 > </ th > < th > </ th > </ tr >
2477
< tr > < td > </ td > < td > </ td > </ tr >
2478
< tr > < td > </ td > < td > </ td > </ tr >
2479
< tr > < td > </ td > < td > </ td > </ tr >
2480
< tr > < td > </ td > < td > </ 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 > </ th > < th > </ th > </ tr >
2492
< tr > < td > </ td > < td > </ td > </ tr >
2493
< tr > < td > </ td > < td > </ td > </ tr >
2494
</ table >
2495
2496
< h4 > < a id = " debugdevicemode1 " > </ 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 > </ code >
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 >
2519
</ pre >
2520
< p >
2521
(when all bits are on, mode register = 0x1F)< br />
2522
or
2523
</ p >
2524
< pre >
2525
</ pre >
2526
< p >
2527
(when the binary bit is off, mode register = 0x1D)< br />
2528
or
2529
</ p >
2530
< pre >
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 " > </ 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 > </ code > < code > </ code >
2572
</ p >
2573
< pre > </ pre >
2574
< p >
2575
and if we substitute < code > </ code > < code > </ code >
2576
</ p >
2577
< pre > </ 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 > </ code > < code > </ code >
2581
</ p >
2582
< pre > </ 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 " > </ 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" > </ 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 " > </ a > </ h4 >
2616
2617
< p >
2618
To enable the programmable device, insert the < code > </ code >
2619
extension. To do this when starting openMSX, simply add
2620
< code > </ code >
2621
already running, you can use the
2622
< code > < a class = " external " href = " commands.html#ext" > </ a > </ code >
2623
</ p >
2624
2625
< h4 > < a id = " programmabledeviceports " > </ 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" > </ a >
2652
</ p >
2653
< div class = " commandline " >
2654
< a class = " external " href = " commands.html#set" > </ a >
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" > </ a >
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" > </ a >
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" > </ a >
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 " > </ 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 > </ code > < code > & lt; & gt; </ code > < code > </ code >
2688
</ p >
2689
2690
< div class = " commandline " >
2691
sdcdb break main.c:155
2692
</ div >
2693
2694
< p > < code > </ code > < code > </ code > < code > </ code > < code > </ code > < code > </ code > < code > </ code > < code > & lt; & gt; </ code > < code > </ code > < code > </ code > </ p >
2695
2696
< h2 > < a id = " contact " > </ 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 > </ code >
2711
< code > </ code > </ a >
2712
and ask your question there. Also reachable via < a class = " external "
2713
href = " https://web.libera.chat/#openMSX" > </ a >
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" >
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" >
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 > </ code >
2733
If you want to address the openMSX developers directly, post a message to the
2734
< code > </ code >
2735
More info on the
2736
< a class = " external " href = " https://sourceforge.net/p/openmsx/mailman" > </ 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 >