Mercurial > repos > blastem
annotate README @ 2688:b42f00a3a937 default tip
Fix default target. Ensure m68k.h and z80.h are built before anything else when no dep info is available
| author | Michael Pavone <pavone@retrodev.com> |
|---|---|
| date | Mon, 31 Mar 2025 21:06:18 -0700 |
| parents | 62f316b76e9a |
| children |
| rev | line source |
|---|---|
| 1662 | 1 BlastEm 0.6.0 |
| 468 | 2 ------------- |
| 3 | |
| 4 Installation | |
| 5 ------------ | |
| 6 | |
| 1662 | 7 Extract this archive to a directory of your choosing. |
| 1066 | 8 |
| 9 NOTE: Prior to version 0.4.1, BlastEm was still using Unixy locations for config | |
| 10 and save files. If you're upgrading from a previous version on Windows, you will | |
| 11 need to move them manually. For config files, the relevant paths are in the | |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
12 previous paragraph. For save files, move all the directories found in |
| 1066 | 13 %userprofile%\.local\share\blastem to %localappdata%\blastem |
| 468 | 14 |
|
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
15 Usage |
|
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
16 ----- |
|
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
17 |
| 1662 | 18 This version of BlastEm has a GUI that allows access to most configuration options. |
| 19 Simply start BlastEm without passing a ROM filename on the command line to access | |
|
2306
62f316b76e9a
Migrate ui.exit to ui.menu and create a new ui.exit for quitting
Michael Pavone <pavone@retrodev.com>
parents:
2289
diff
changeset
|
20 the main menu. You can also access the menu by hitting the button mapped to the ui.menu |
| 1662 | 21 action (default Esc). |
| 22 | |
|
2306
62f316b76e9a
Migrate ui.exit to ui.menu and create a new ui.exit for quitting
Michael Pavone <pavone@retrodev.com>
parents:
2289
diff
changeset
|
23 If you explicitly request it, you can still use the old ROM-based UI instead. This UI does |
|
62f316b76e9a
Migrate ui.exit to ui.menu and create a new ui.exit for quitting
Michael Pavone <pavone@retrodev.com>
parents:
2289
diff
changeset
|
24 not support configuration so you will need to modify the configuration file manually if you |
|
62f316b76e9a
Migrate ui.exit to ui.menu and create a new ui.exit for quitting
Michael Pavone <pavone@retrodev.com>
parents:
2289
diff
changeset
|
25 use it. See the rest of this README for instructions on modifying the configuration file. |
| 1013 | 26 |
| 27 Some operations are currently only supported through the command line. To get a | |
| 28 list of supported command line options on Linux or OSX type: | |
|
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
29 |
| 1066 | 30 ./blastem -h |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
31 |
|
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
32 From within your BlastEm directory. On Windows type: |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
33 |
| 1066 | 34 blastem.exe -h |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
35 |
|
1017
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
36 Lock-On Support |
|
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
37 --------------- |
|
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
38 |
|
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
39 This version of BlastEm has some preliminary support for Sonic & Knuckles lock |
|
1442
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
40 on technology. This is available via both the menu and the command line. To use |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
41 it from the menu, first load Sonic & Knuckles normally. Enter the menu (mapped |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
42 to the Escape key by default) and select the "Lock On" option to select a ROM |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
43 to lock on. The system will then reload with the combined game. To use it from |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
44 the command line, specify the Sonic & Knuckles ROM as the primary ROM and |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
45 specify the ROM to be locked on using the -o option. As an example: |
|
1017
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
46 |
| 1066 | 47 ./blastem ~/romz/sonic_and_knuckles.bin -o ~/romz/sonic3.bin |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
48 |
|
1442
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
49 Please note that Sonic 2 lock-on does not work at this time. |
|
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
50 |
| 468 | 51 Configuration |
| 52 ------------- | |
| 53 | |
| 1066 | 54 Configuration is read from the file at $HOME/.config/blastem/blastem.cfg on |
| 55 Unix-like systems and %localappdata%\blastem\blastem.cfg if it exists. | |
| 56 Othwerise it is read from default.cfg from the same directory as the BlastEm | |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
57 executable. Sections are denoted by a section name followed by an open curly |
| 1066 | 58 bracket, the section's contents and a closing curly bracket. Individual |
| 468 | 59 configuration values are set by entering the value's name followed by a space |
| 60 or tab and followed by the desired value. | |
| 61 | |
| 62 Bindings | |
| 63 -------- | |
| 64 | |
| 65 The keys subsection of bindings maps keyboard keys to gamepad buttons or UI | |
| 66 actions. The key name goes on the left and the action is on the right. | |
| 1066 | 67 Most keys are named for the character they produce when pressed. For keys that |
| 68 don't correspond to a normal character, check the list below: | |
| 69 | |
| 70 Name | Description | |
| 71 ----------------- | |
| 72 up Up arrow | |
| 73 down Down arrow | |
| 74 left Left arrow | |
| 75 right Right arrow | |
| 76 space | |
| 77 tab | |
| 78 backspace Backspace on PC keyboards, Delete on Mac keyboards | |
| 79 esc | |
| 80 delete | |
| 81 lshift Left shift | |
| 82 rshift Right shift | |
| 83 lctrl Left control | |
| 84 rctrl Right control | |
| 85 lalt Left alt on PC keyboards, Option on Mac keyboards | |
| 86 ralt Right alt on PC keyboards, Option on Mac keyboards | |
| 87 home | |
| 88 end | |
| 89 pageup | |
| 90 pagedown | |
| 91 f1 | |
| 92 f2 | |
| 93 f3 | |
| 94 f4 | |
| 95 f5 | |
| 96 f6 | |
| 97 f7 | |
| 98 f8 | |
| 99 f9 | |
| 100 f10 | |
| 101 f11 | |
| 102 f12 | |
| 103 select | |
| 104 play | |
| 105 search | |
| 106 back | |
| 468 | 107 |
|
1227
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
108 The pads subsection is used to map gamepads and joysticks. Gamepads that are |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
109 recognized, can have their buttons and axes mapped with semantic names. |
|
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
110 Xbox 360, PS4 and PS3 style names are supported. Unrecognized gamepads can be |
|
1227
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
111 mapped using numeric button and axis ids. The following button names are |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
112 recognized by BlastEm: |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
113 a, cross |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
114 b, circle |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
115 x, square |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
116 y, trinagle |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
117 start, options |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
118 back, select, share |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
119 guide |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
120 leftbutton, l1 |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
121 rightbutton, r1 |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
122 leftstick, l3 |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
123 rightstick, r3 |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
124 The following axis names are recognized by BlastEm: |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
125 leftx |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
126 lefty |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
127 rightx |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
128 righty |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
129 lefttrigger, l2 |
|
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
130 righttrigger, r2 |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
131 |
| 1013 | 132 |
| 133 The mice subsection is used to map mice to emulated Mega/Sega mice. The default | |
| 134 configuration maps both the first and second host mice to the first emulated | |
| 135 mouse. This should not need modification for most users. | |
| 136 | |
| 137 One special mapping deserves a mention. By default, the 'r' key is mapped to | |
| 138 ui.release_mouse. When operating in windowed mode the mouse has a capture | |
| 139 behavior. Mouse events are ignored until you click in the window. The mouse | |
| 140 will then be "captured" and the cursor will be both made invisible and locked | |
| 141 to the window. The ui.release_mouse binding releases the mouse so it can be | |
| 142 used normally. | |
| 143 | |
|
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
144 UI Actions |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
145 ---------- |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
146 |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
147 This section lists the various "UI" actions that can be triggered by a key or |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
148 gamepad binding. |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
149 |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
150 ui.release_mouse Releases the mouse if it is currently captured |
| 1662 | 151 ui.plane_debug Toggles the VDP plane debug view |
| 152 ui.vram_debug Toggles the VDP VRAM debug view | |
| 153 ui.cram_debug Toggles the VDP CRAM debug view | |
| 154 ui.compositing_debug Toggles the VDP compositing debug view | |
| 155 ui.vdp_debug_mode Cycles the mode/palette of the VDP debug view | |
| 156 that currently has focus | |
|
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
157 ui.enter_debugger Enters the debugger for the main CPU of the |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
158 currently emulated system |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
159 ui.screenshot Takes an internal screenshot |
|
2306
62f316b76e9a
Migrate ui.exit to ui.menu and create a new ui.exit for quitting
Michael Pavone <pavone@retrodev.com>
parents:
2289
diff
changeset
|
160 ui.menu Opens the in-game menu, or exits the menu if it |
|
62f316b76e9a
Migrate ui.exit to ui.menu and create a new ui.exit for quitting
Michael Pavone <pavone@retrodev.com>
parents:
2289
diff
changeset
|
161 is currently open. |
|
62f316b76e9a
Migrate ui.exit to ui.menu and create a new ui.exit for quitting
Michael Pavone <pavone@retrodev.com>
parents:
2289
diff
changeset
|
162 ui.exit Quits the emulator |
|
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
163 ui.save_state Saves a savestate to the quicksave slot |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
164 ui.set_speed.N Selects a specific machine speed specified by N |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
165 which should be a number between 0-9. Speeds are |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
166 specified in the "clocks" section of the config |
|
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
167 ui.next_speed Selects the next machine speed |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
168 ui.prev_speed Selects the previous machine speed |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
169 ui.toggle_fullscreen Toggles between fullscreen and windowed mode |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
170 ui.soft_reset Resets a portion of the emulated machine |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
171 Equivalent to pushing the reset button on the |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
172 emulated device |
|
1442
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
173 ui.reload Reloads the current ROM from a file and performs |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
174 a hard reset of the emulated device |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
175 ui.sms_pause Triggers a press of the pause button when in SMS |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
176 mode |
|
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
177 ui.toggle_keyboard_captured Toggles the capture state of the host keyboard |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
178 when an emulated keyboard is present |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
179 |
| 1013 | 180 IO |
| 181 -- | |
| 182 | |
| 183 This section controls which peripherals are attached to the emulated console. | |
| 184 IO assignments can be overridden by the ROM database when appropriate. For | |
| 185 instance, games with mouse support can automatically use the mouse and games | |
| 186 that only support 3-button pads can automatically force an appropriate pad. | |
| 187 Unforunately, the ROM database is not yet exhaustive so manual configuration | |
| 188 may be needed here in some cases. | |
| 468 | 189 |
| 190 Video | |
| 191 ----- | |
| 192 | |
| 1013 | 193 The video section contains settings that affect the visual output of BlastEm. |
| 194 | |
|
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
195 "aspect" is used to control the aspect ratio of the emulated display. The |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
196 default of 4:3 matches that of a standard definition television. |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
197 |
|
1442
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
198 "width" is used to control the window width when not in fullscreen mode. |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
199 |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
200 "height" is used to control the window height when not in fullscreen mode. If |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
201 left unspecified, it will be calculated from "width" and "aspect". |
| 1013 | 202 |
| 203 "vertex_shader" and "fragment_shader" define the GLSL shader program that | |
| 204 produces the final image for each frame. Shaders can be used to add various | |
| 205 visual effects or enhancements. Currently BlastEm only ships with the default | |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
206 shader and a "subtle" crt shader. If you write your own shaders, place them in |
| 1013 | 207 $HOME/.config/blastem/shaders and then specify the basename of the new shader |
| 208 files in the "vertex_shader" and "fragment_shader" config options. Note that | |
| 209 shaders are not available in the SDL fallback renderer. | |
| 210 | |
| 211 "scanlines" controls whether there is any emulation of the gaps between display | |
| 212 lines that are present when driving a CRT television with a 240p signal. This | |
| 213 emulation is very basic at the moment so this option is off by default. | |
| 214 | |
| 215 "vsync" controls whether the drawing of frames is synchronized to the monitor | |
| 216 refresh rate. Valid values for this setting are "off", "on" and "tear". The | |
| 217 latter will attempt to use the "late tear" option if it's available and normal | |
| 218 vsync otherwise. Currently it's recommended to leave this at the default of | |
| 1662 | 219 "off" as it may not work well with the default "audio" sync method and the |
| 220 "video" sync method will automatically enable "vsync". See "Sync Source and | |
| 221 VSync" for more details. | |
| 468 | 222 |
|
1017
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
223 "fullscreen" controls whether BlastEm starts in fullscreen or windowed mode. |
|
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
224 This can be overridden on the command line with the -f flag. If fullscreen |
|
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
225 is set to "off", -f will turn it on. Conversely, if fullscreen is set to "on" |
|
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
226 in the config, -f will turn it off. |
|
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
227 |
|
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
228 "gl" controls whether OpenGL is used for rendering. The default value is on. |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
229 If it is set to off instead, the fallback renderer which uses SDL2's render API |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
230 will be used instead. This option is mostly useful for users on hardware that |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
231 lacks OpenGL 2 support. While BlastEm will fall back automatically even if gl |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
232 is set to on there will be a warning. Disabling gl eliminates this warning. |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
233 |
|
1442
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
234 "scaling" controls the type of scaling used for textures in both the GL and |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
235 SDL renderers. Valid values are "nearest" and "linear". Note that shaders also |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
236 impact how pixels are scaled. |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
237 |
|
1352
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
238 The "ntsc" and "pal" sub-sections control overscan settings for the emulated |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
239 video output for NTSC and PAL consoles respectively. More details are available |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
240 in the Overscan section. |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
241 |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
242 Overscan |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
243 -------- |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
244 |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
245 Analog televisions generally don't display the entirety of a video frame. Some |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
246 portion is cropped at the edges of the display. This is called overscan. |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
247 Unfortunately, the amount of cropping performed varies considerably and is even |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
248 adjustable on many TV sets. To deal with this, BlastEm allows overscan to be |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
249 customized. |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
250 |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
251 Overscan values are specified in the "ntsc" and "pal" sub-sections of the |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
252 "video" section of the config file. The "overscan" sub-section contains four |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
253 settings for specifying the number of pixels cropped on each side of the |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
254 display: "top", "bottom", "left" and "right". |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
255 |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
256 The default settings hide the horizontal border completely for both NTSC and |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
257 PAL consoles. For the vertical borders, the NTSC overscan settings are chosen |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
258 to give square pixels with the default aspect ratio of 4:3. For PAL, the |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
259 default settings are set so that the PAL-exclusive V30 mode will produce a |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
260 visible border that is the same size as what is shown in V28 mode in NTSC. This |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
261 results in a slightly squished picture compared to NTSC which is probably |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
262 appropriate given that a PAL display has more lines than an NTSC one. |
|
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
263 |
| 468 | 264 Audio |
| 265 ----- | |
| 266 | |
| 1014 | 267 The audio section contains settings that affect the audio output of BlastEm. |
| 1013 | 268 |
| 269 "rate" selects the preferred sample rate for audio output. Your operating | |
| 270 system may not accept this value in which case a different rate will be chosen. | |
| 271 This should generally be either the native sample rate of your sound card or an | |
| 272 integral divisor of it. Most modern sound cards have a native output rate that | |
| 273 is a multiple of 48000 Hz so the default setting should work well for most users. | |
| 274 | |
| 275 "buffer size" controls how large of a buffer uses for audio data. Smaller values | |
| 276 will reduce latency, but too small of a value can lead to dropouts. 512 works | |
| 277 well for me, but a higher or lower value may be more appropriate for your system. | |
| 278 | |
| 279 "lowpass_cutoff" controls the cutoff, or knee, frequency of the RC-style | |
| 280 low-pass filter. The default value of 3390 Hz is supposedly what is present in | |
| 281 at least some Genesis/Megadrive models. Other models reportedly use an even | |
| 282 lower value. | |
| 468 | 283 |
|
1812
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
284 "gain" specifies the gain in decibels to be applied to the overall output. |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
285 |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
286 "fm_gain" specifies the gain to be applied to the emulated FM output before |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
287 mixing with the PSG. |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
288 |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
289 "psg_gain" specifies the gain to be applied to the emulated PSG output before |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
290 mixing with the FM chip. |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
291 |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
292 "fm_dac" controls the characteristics of the DAC in the emulated FM chip. If |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
293 this is set to "linear", then the DAC will have precise linear output similar |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
294 to the integrated YM3438 in later Gen/MD consoles. If it is set to "zero_offset", |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
295 there will be a larger gap between -1 and 0. This is commonly referred to as the |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
296 "ladder effect". This will also cause "leakage" on channels that are muted or |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
297 panned to one side in a similar manner to a discrete YM2612. |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
298 |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
299 |
| 1014 | 300 Clocks |
| 301 ------ | |
| 302 | |
| 303 The clocks section contains settings that affect how fast things run. | |
| 304 | |
| 305 "m68k_divider" describes the relationsip between the master clock (which is | |
| 306 53693175 Hz for NTSC mode and 53203395 Hz for PAL mode). The default value of 7 | |
| 307 matches the real hardware. Set this to a lower number to overclock the 68000 | |
| 308 and set it to a higher number to underclock it. | |
| 309 | |
| 310 "max_cycles" controls how often the system is forced to synchronize all | |
| 311 hardware. BlastEm generally uses a sync on demand approach to synchronizing | |
| 312 components in the system. This can provide perfect synchronization for most | |
| 313 components, but since the Z80 can steal cycles from the 68000 at unpredictable | |
| 314 times 68000/Z80 synchronization is imperfect. The default value of 3420 | |
| 315 corresponds to the number of master clock cycles per line. Larger numbers may | |
| 316 produce a modest performance improvement whereas smaller numbers will improve | |
| 317 68000/Z80 synchronization. | |
| 318 | |
| 319 "speeds" controls the speed of the overall emulated console at different | |
| 320 presets. Preset 0 is the default speed and should normally be set to 100. The | |
| 321 other presets enable the slow/turbo mode functionality. | |
| 322 | |
| 323 UI | |
| 324 -- | |
| 325 | |
|
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
326 The UI section contains settings that affect the user interface. |
| 1014 | 327 |
| 328 "rom" determines the path of the Genesis/Megadrive ROM that implements the UI. | |
| 329 Relative paths will be loaded relative to the BlastEm executable. | |
| 330 | |
|
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
331 "initial_path" specifies the starting path for the ROM browser. It can contain |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
332 the following special variables: $HOME, $EXEDIR. Additionally, variables |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
333 defined in the OS environment can be used. |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
334 |
|
1442
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
335 "remember_path" specifies whether BlastEm should remember the last path used in |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
336 the file browser. When it is set to "on", the last path will be remembered and |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
337 used instead of "initial_path" in subsequent runs. If it is set to "off", |
|
1442
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
338 "initial_path" will always be used. |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
339 |
|
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
340 "screenshot_path" specifies the directory "internal" screenshots will be saved |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
341 in. It accepts the same special variables as "initial_path". |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
342 |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
343 "screenshot_template" specifies a template for creating screenshot filenames. |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
344 It is specified as a format string for the C library function strftime |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
345 |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
346 "save_path" specifies the directory that savestates, SRAM and EEPROM data will |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
347 be saved in for a given game. It can contain the following special variables: |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
348 $HOME, $EXEDIR, $USERDATA, $ROMNAME. Like "initial_path" it can also reference |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
349 variables from the environment. |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
350 |
|
1442
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
351 "extensions" specifies the file extensions that should be displayed in the file |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
352 browser. |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
353 |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
354 "state_format" specifies the preferred format for saving save states. Valid |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
355 values are "native" (the default) and "gst". "native" save states do a better |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
356 job of preserving the state of the emulated system, but "gst" save states are |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
357 compatible with other emulators like Kega and Gens. This setting has no effect |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
358 for systems other than the Genesis/Mega Drive |
|
59e1dbb795a7
Update README in anticipation of 0.5.1 release
Michael Pavone <pavone@retrodev.com>
parents:
1354
diff
changeset
|
359 |
|
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
360 Path Variables |
| 1014 | 361 -------------- |
| 362 | |
|
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
363 This section explains the meaning of the special path variables referenced |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
364 in the previous section. |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
365 |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
366 $HOME The home directory of the current user. On most Unix variants, it |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
367 will be a subdirectory of /home. On Windows it will typically be a |
|
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
368 subdirectory of C:\Users |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
369 $EXEDIR The directory the BlastEm executable is located in |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
370 $USERDATA This is an OS-specific path used for storing application specific |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
371 user data. On Unix variants, it will be $HOME/.local/share/blastem |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
372 On Windows it will be %LOCALDATA%/blastem |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
373 $ROMNAME The name of the currently loaded ROM file without the extension |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
374 |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
375 System |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
376 ------ |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
377 |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
378 "ram_init" determines how the RAM in the emulated system is initialized. The |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
379 default value of "zero" will cause all RAM to be zeroed out before the system |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
380 is started. Alternatively, "random" can be used to initialize RAM with values |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
381 from a pseudo-random number generator. This option is mostly useful for |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
382 developers that want to debug initialization issues in their code. |
|
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
383 |
| 1014 | 384 "default_region" determines the console region that will be used when region |
| 385 detection fails and when there are multiple valid regions. The default of 'U' | |
| 1662 | 386 specifies a 60Hz "foreign" console. |
| 387 | |
| 388 "sync_source" controls whether BlastEm uses audio or video output to control | |
| 389 execution speed. "video" can provide a smoother experience when your display | |
| 390 has a similar refresh rate to the emulated system, but has some limitations | |
| 391 in the current version. The default value is "audio". | |
| 392 | |
| 393 "megawifi" enables or disables support for MegaWiFi cart emulation. MegaWiFi | |
| 394 is a cartridge that contains WiFi hardware for network functionality. Enabling | |
| 395 this means that ROMs potentially have access to your network (and the internet) | |
| 396 which obviously has security implications. For this reason, it is disabled by | |
| 397 default. If you wish to try out MegaWiFi emulation, set this to "on". Note that | |
| 398 the support for MegaWiFi hardware is preliminary in this release. | |
| 1014 | 399 |
| 468 | 400 Debugger |
| 401 -------- | |
| 402 | |
| 403 BlastEm has an integrated command-line debugger loosely based on GDB's | |
| 404 interface. The interface is very rough at the moment. Available commands in the | |
| 405 68K debugger are: | |
| 1066 | 406 b ADDRESS - Set a breakpoint at ADDRESS |
| 407 d BREAKPOINT - Delete a 68K breakpoint | |
| 408 co BREAKPOINT - Run a list of debugger commands each time | |
| 1014 | 409 BREAKPOINT is hit |
| 1066 | 410 a ADDRESS - Advance to address |
| 411 n - Advance to next instruction | |
| 412 o - Advance to next instruction ignoring branches to | |
| 413 lower addresses (good for breaking out of loops) | |
| 414 s - Advance to next instruction (follows bsr/jsr) | |
| 415 c - Continue | |
| 416 bt - Print a backtrace | |
| 417 p[/(x|X|d|c)] VALUE - Print a register or memory location | |
| 418 di[/(x|X|d|c)] VALUE - Print a register or memory location each time | |
| 419 a breakpoint is hit | |
| 420 vs - Print VDP sprite list | |
| 421 vr - Print VDP register info | |
| 422 zb ADDRESS - Set a Z80 breakpoint | |
| 423 zp[/(x|X|d|c)] VALUE - Display a Z80 value | |
| 424 q - Quit BlastEm | |
| 468 | 425 Available commands in the Z80 debugger are: |
| 1066 | 426 b ADDRESS - Set a breakpoint at ADDRESS |
| 427 de BREAKPOINT - Delete a Z80 breakpoint | |
| 428 a ADDRESS - Advance to address | |
| 429 n - Advance to next instruction | |
| 430 c - Continue | |
| 431 p[/(x|X|d|c)] VALUE - Print a register or memory location | |
| 432 di[/(x|X|d|c)] VALUE - Print a register or memory location each time | |
| 433 a breakpoint is hit | |
| 434 q - Quit BlastEm | |
| 468 | 435 |
| 436 The -d flag can be used to cause BlastEm to start in the debugger. | |
| 437 Alternatively, you can use the ui.enter_debugger action (mapped to the 'u' key | |
| 1014 | 438 by default) to enter the debugger while a game is running. To debug the menu |
| 439 ROM, use the -dm flag. | |
| 468 | 440 |
| 536 | 441 GDB Remote Debugging |
| 442 -------------------- | |
| 443 | |
| 444 In addition to the native debugger, BlastEm can also act as a GDB remote | |
| 445 debugging stub. To use this, you'll want to configure your Makefile to produce | |
| 446 both an ELF executable and a raw binary. Invoke an m68k-elf targeted gdb with | |
| 447 the ELF file. Once inside the gdb session, type: | |
| 448 | |
| 1066 | 449 target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D |
| 536 | 450 |
| 451 where BLASTEM_PATH is the relative or absolute path to your BlastEm | |
| 452 installation and ROM_FILE.bin is the name of the raw binary for your program. | |
| 453 BlastEm will halt at the beginning of your program's entry point and return | |
| 454 control to GDB. This will allow you to set breakpoints before your code runs. | |
| 455 | |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
456 On Windows, the procedure is slightly different. First run |
| 1066 | 457 blastem.exe ROM_FILE.bin -D |
|
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
458 This will cause BlastEm to wait for a socket connection on port 1234. It will |
|
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
459 appear to be frozen until gdb connects to it. Now open the ELF file in gdb |
|
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
460 and type: |
|
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
461 |
| 1066 | 462 target remote :1234 |
|
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
463 |
| 536 | 464 Trace points and watch points are not currently supported. |
| 465 | |
|
810
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
466 Included Tools |
|
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
467 -------------- |
|
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
468 |
|
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
469 BlastEm ships with a few small utilities that leverage portions of the emulator |
|
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
470 code. |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
471 |
| 1066 | 472 dis - 68K disassembler |
| 473 zdis - Z80 disassembler | |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
474 |
| 1662 | 475 Sync Source and VSync |
| 1013 | 476 ----- |
| 477 | |
| 1662 | 478 This section includes information about using VSync with BlastEm. Currently, |
| 479 the best way to use VSync is to set the sync source to "video". This will force | |
| 480 VSync on and use video output for controlling the speed of emulation. In this | |
| 481 mode, audio will have it's rate automatically adjusted to keep pace with video. | |
| 482 The code for this is still a bit immature, so you may experience dropouts or | |
| 483 pitch changes in this mode. | |
| 1014 | 484 |
| 1662 | 485 If you experience problems, please switch back to the "audio" sync source, |
| 486 which is the default. You can also enable vsync when using the "audio" sync | |
| 487 source by changing the "vsync" setting. This will generally work okay as long | |
| 488 as the emulated refresh rate is below your monitor refresh rate (even if only | |
| 489 slightly), but you will occassionally get a doubled frame (or frequently if | |
| 490 the refresh rates are very different). | |
| 1014 | 491 |
| 1662 | 492 Turbo mode will currently not work when vsync is on, regardless of which sync |
| 493 source is used. Slow mode will work with "audio" sync, but not "video" sync. | |
| 1014 | 494 |
| 1066 | 495 -------------- |
| 496 | |
| 497 My work has been made much easier by the contributions of those in the Genesis | |
| 498 community past and present. I'd like to thank the people below for their help. | |
| 499 | |
| 500 Nemesis - His work reverse engineering and documenting the VDP and | |
| 501 YM-2612 has saved me an immeasurable amount of time. I've | |
| 502 found both his sprite overflow test ROM and VDP FIFO | |
| 503 Testing ROM to be quite helpful. | |
| 504 | |
| 505 Charles MacDonald - While it hasn't been updated in a while, I still find his | |
| 506 VDP document to be my favorite reference. His Genesis | |
| 507 hardware document has also come in handy. | |
| 508 | |
| 509 Eke-Eke - Eke-Eke wrote a great document on the use of I2C EEPROM in | |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
510 Genesis games and also left some useful very helpful |
| 1066 | 511 comments about problematic games in Genesis Plus GX |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
512 |
|
1812
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
513 Sauraen - Sauraen has analyzed the YM2203 and YM2612 dies and written |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
514 a VHDL operator implementation. These have been useful in |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
515 improving the accuracy of my YM2612 core. |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
516 |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
517 Alexey Khokholov - Alexey (aka Nuke.YKT) has analyzed the YM3438 die and written |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
518 a fairly direct C implementation from that analysis. This |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
519 has been a useful reference for verifying and improving my |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
520 YM2612 core. |
| 1066 | 521 |
| 522 Bart Trzynadlowski - His documents on the Genecyst save-state format and the | |
| 523 mapper used in Super Street Fighter 2 were definitely | |
| 524 appreciated. | |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
525 |
| 1066 | 526 KanedaFR - Kaneda's SpritesMind forum is a great resource for the |
| 527 Sega development community. | |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
528 |
|
1354
34798ad9c570
Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents:
1353
diff
changeset
|
529 Titan - Titan has created what are without a doubt the most |
|
34798ad9c570
Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents:
1353
diff
changeset
|
530 impressive demos on the Megadrive. Additionally, I am very |
|
34798ad9c570
Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents:
1353
diff
changeset
|
531 grateful for the documentation provided by Kabuto and the |
|
34798ad9c570
Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents:
1353
diff
changeset
|
532 assistance of Kabuto, Sik and Jorge in getting Overdrive 2 |
| 1661 | 533 to run properly in BlastEm. |
|
2289
92449b47cce8
Integrate VGM player into main blastem binary
Michael Pavone <pavone@retrodev.com>
parents:
1812
diff
changeset
|
534 |
| 1661 | 535 flamewing - flamewing created a very handy exhaustive test ROM for 68K |
| 536 BCD instructions and documented the proper behavior for | |
| 537 certain BCD edge cases | |
| 538 | |
| 539 r57shell - r57shell created a test ROM for 68K instruction sizes that | |
| 540 was invaluable in fixing the remaining bugs in my 68K instruction | |
| 541 decoder | |
| 1066 | 542 |
| 543 I'd also like to thank the following people who have performed compatibility | |
| 544 testing or submitted helpful bug reports | |
| 545 | |
|
1354
34798ad9c570
Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents:
1353
diff
changeset
|
546 micky, Sasha, lol-frank, Sik, Tim Lawrence, ComradeOj, Vladikcomper |
| 1066 | 547 |
| 468 | 548 License |
| 549 ------- | |
| 550 | |
| 551 BlastEm is free software distributed under the terms of the GNU General Public | |
| 552 License version 3 or higher. This gives you the right to redistribute and/or | |
| 553 modify the program as long as you follow the terms of the license. See the file | |
| 554 COPYING for full license details. | |
| 555 | |
|
1812
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
556 Binary releases of BlastEm are packaged with GLEW, SDL2 and zlib which have their |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
557 own licenses. See GLEW-LICENSE and SDL-LICENSE for details. For zlib license |
|
8aeac7bd9fa7
Update version number, special thanks, CHANGELOG and README in preparation for possible 0.6.2 release
Michael Pavone <pavone@retrodev.com>
parents:
1662
diff
changeset
|
558 information, please see zlib.h in the source code release. |