Mercurial > repos > blastem
annotate README @ 1388:af870e265226
Add device override for Fun n Games as it supports the mouse
author | Michael Pavone <pavone@retrodev.com> |
---|---|
date | Fri, 02 Jun 2017 00:36:07 -0700 |
parents | 34798ad9c570 |
children | 59e1dbb795a7 |
rev | line source |
---|---|
1227
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
1 BlastEm 0.5.0 |
468 | 2 ------------- |
3 | |
4 Installation | |
5 ------------ | |
6 | |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
7 Extract this archive to a directory of your choosing. If you wish to change the |
1066 | 8 configuration settings, copy default.cfg to $HOME/.config/blastem/blastem.cfg |
9 and modify the copy. If you are on Windows, the config file should be placed in | |
10 %localappdata%\blastem. You may also whish to add the blastem directory to your | |
11 PATH environment variable. | |
12 | |
13 NOTE: Prior to version 0.4.1, BlastEm was still using Unixy locations for config | |
14 and save files. If you're upgrading from a previous version on Windows, you will | |
15 need to move them manually. For config files, the relevant paths are in the | |
16 previous paragraph. For save files, move all the directories found in | |
17 %userprofile%\.local\share\blastem to %localappdata%\blastem | |
468 | 18 |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
19 Usage |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
20 ----- |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
21 |
1013 | 22 This version of BlastEm has an experimental GUI that is implemented as a Genesis |
23 ROM running inside the emulator. This UI can be operated with either a mouse or | |
24 the first emulated gamepad. By default, both the keyboard and the first game | |
25 controller are mapped to said gamepad. For more information on bindings see the | |
26 Bindings section. | |
27 | |
28 Some operations are currently only supported through the command line. To get a | |
29 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
|
30 |
1066 | 31 ./blastem -h |
32 | |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
33 From within your BlastEm directory. On Windows type: |
1066 | 34 |
35 blastem.exe -h | |
36 | |
1017
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
37 Lock-On Support |
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 |
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
40 This version of BlastEm has some preliminary support for Sonic & Knuckles lock |
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
41 on technology. This is only available from the command line at the moment. To |
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
42 use it specify the Sonic & Knuckles ROM as the primary ROM and specify the ROM |
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
43 to be locked on using the -o option. As an example: |
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
44 |
1066 | 45 ./blastem ~/romz/sonic_and_knuckles.bin -o ~/romz/sonic3.bin |
46 | |
1017
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
47 Please note that Sonic 2 lock-on does not work at this time. Additionally the |
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
48 save RAM added by Sonic 3 won't work either. |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
49 |
468 | 50 Configuration |
51 ------------- | |
52 | |
1066 | 53 Configuration is read from the file at $HOME/.config/blastem/blastem.cfg on |
54 Unix-like systems and %localappdata%\blastem\blastem.cfg if it exists. | |
55 Othwerise it is read from default.cfg from the same directory as the BlastEm | |
56 executable. Sections are denoted by a section name followed by an open curly | |
57 bracket, the section's contents and a closing curly bracket. Individual | |
468 | 58 configuration values are set by entering the value's name followed by a space |
59 or tab and followed by the desired value. | |
60 | |
61 Bindings | |
62 -------- | |
63 | |
64 The keys subsection of bindings maps keyboard keys to gamepad buttons or UI | |
65 actions. The key name goes on the left and the action is on the right. | |
1066 | 66 Most keys are named for the character they produce when pressed. For keys that |
67 don't correspond to a normal character, check the list below: | |
68 | |
69 Name | Description | |
70 ----------------- | |
71 up Up arrow | |
72 down Down arrow | |
73 left Left arrow | |
74 right Right arrow | |
75 space | |
76 tab | |
77 backspace Backspace on PC keyboards, Delete on Mac keyboards | |
78 esc | |
79 delete | |
80 lshift Left shift | |
81 rshift Right shift | |
82 lctrl Left control | |
83 rctrl Right control | |
84 lalt Left alt on PC keyboards, Option on Mac keyboards | |
85 ralt Right alt on PC keyboards, Option on Mac keyboards | |
86 home | |
87 end | |
88 pageup | |
89 pagedown | |
90 f1 | |
91 f2 | |
92 f3 | |
93 f4 | |
94 f5 | |
95 f6 | |
96 f7 | |
97 f8 | |
98 f9 | |
99 f10 | |
100 f11 | |
101 f12 | |
102 select | |
103 play | |
104 search | |
105 back | |
468 | 106 |
1227
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
107 The pads subsection is used to map gamepads and joysticks. Gamepads that are |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
108 recognized, can have their buttons and axes mapped with semantic names. |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
109 Xbox 360, PS4 and PS3 style names are supported. Unrecognized gamepads can be |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
110 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
|
111 recognized by BlastEm: |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
112 a, cross |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
113 b, circle |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
114 x, square |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
115 y, trinagle |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
116 start, options |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
117 back, select, share |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
118 guide |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
119 leftbutton, l1 |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
120 rightbutton, r1 |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
121 leftstick, l3 |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
122 rightstick, r3 |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
123 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
|
124 leftx |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
125 lefty |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
126 rightx |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
127 righty |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
128 lefttrigger, l2 |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
129 righttrigger, r2 |
262c0ce8f586
WIP update to README for 0.5.0
Michael Pavone <pavone@retrodev.com>
parents:
1069
diff
changeset
|
130 |
1013 | 131 |
132 The mice subsection is used to map mice to emulated Mega/Sega mice. The default | |
133 configuration maps both the first and second host mice to the first emulated | |
134 mouse. This should not need modification for most users. | |
135 | |
136 One special mapping deserves a mention. By default, the 'r' key is mapped to | |
137 ui.release_mouse. When operating in windowed mode the mouse has a capture | |
138 behavior. Mouse events are ignored until you click in the window. The mouse | |
139 will then be "captured" and the cursor will be both made invisible and locked | |
140 to the window. The ui.release_mouse binding releases the mouse so it can be | |
141 used normally. | |
142 | |
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
143 UI Actions |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
144 ---------- |
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 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
|
147 gamepad binding. |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
148 |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
149 ui.release_mouse Releases the mouse if it is currently captured |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
150 ui.vdp_debug_mode Cycles through the various VDP debug views |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
151 ui.vdp_debug_pal Cycles through the selected palette when viewing |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
152 the VDP memory viewer |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
153 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
|
154 currently emulated system |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
155 ui.screenshot Takes an internal screenshot |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
156 ui.exit Returns to the menu ROM if currently in a game |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
157 that was launched from the menu. Exits otherwise |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
158 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
|
159 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
|
160 which should be a number between 0-9. Speeds are |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
161 specified in the "clocks" section of the config |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
162 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
|
163 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
|
164 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
|
165 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
|
166 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
|
167 emulated device |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
168 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
|
169 when an emulated keyboard is present |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
170 |
1013 | 171 IO |
172 -- | |
173 | |
174 This section controls which peripherals are attached to the emulated console. | |
175 IO assignments can be overridden by the ROM database when appropriate. For | |
176 instance, games with mouse support can automatically use the mouse and games | |
177 that only support 3-button pads can automatically force an appropriate pad. | |
178 Unforunately, the ROM database is not yet exhaustive so manual configuration | |
179 may be needed here in some cases. | |
468 | 180 |
181 Video | |
182 ----- | |
183 | |
1013 | 184 The video section contains settings that affect the visual output of BlastEm. |
185 | |
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
186 "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
|
187 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
|
188 |
1013 | 189 "width" is used to control the window size when not in fullscreen mode. The |
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
190 height of the window is calculated from this value and "aspect". Both width |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
191 and height can be overridden from the command line. |
1013 | 192 |
193 "vertex_shader" and "fragment_shader" define the GLSL shader program that | |
194 produces the final image for each frame. Shaders can be used to add various | |
195 visual effects or enhancements. Currently BlastEm only ships with the default | |
196 shader. If you write your own shaders, place them in | |
197 $HOME/.config/blastem/shaders and then specify the basename of the new shader | |
198 files in the "vertex_shader" and "fragment_shader" config options. Note that | |
199 shaders are not available in the SDL fallback renderer. | |
200 | |
201 "scanlines" controls whether there is any emulation of the gaps between display | |
202 lines that are present when driving a CRT television with a 240p signal. This | |
203 emulation is very basic at the moment so this option is off by default. | |
204 | |
205 "vsync" controls whether the drawing of frames is synchronized to the monitor | |
206 refresh rate. Valid values for this setting are "off", "on" and "tear". The | |
207 latter will attempt to use the "late tear" option if it's available and normal | |
208 vsync otherwise. Currently it's recommended to leave this at the default of | |
209 "off" as BlastEm synchronizes to audio and does not yet have the necessary code | |
210 to fully handle conflicts between the audio rate and monitor refresh rate. | |
211 Additionally, the "turbo" feature does not function properly with vsync | |
212 enabled. These issues will be addressed in a future release. If you wish to use | |
213 vsync, please see the VSync section at the bottom of the README. | |
468 | 214 |
1017
216fa63749b3
Added documentation for lock-on support and a fullscreen config option.
Michael Pavone <pavone@retrodev.com>
parents:
1014
diff
changeset
|
215 "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
|
216 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
|
217 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
|
218 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
|
219 |
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
220 "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
|
221 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
|
222 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
|
223 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
|
224 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
|
225 |
1352
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
226 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
|
227 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
|
228 in the Overscan section. |
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
229 |
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
230 Overscan |
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
231 -------- |
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
232 |
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
233 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
|
234 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
|
235 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
|
236 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
|
237 customized. |
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
238 |
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
239 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
|
240 "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
|
241 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
|
242 display: "top", "bottom", "left" and "right". |
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 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
|
245 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
|
246 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
|
247 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
|
248 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
|
249 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
|
250 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
|
251 |
468 | 252 Audio |
253 ----- | |
254 | |
1014 | 255 The audio section contains settings that affect the audio output of BlastEm. |
1013 | 256 |
257 "rate" selects the preferred sample rate for audio output. Your operating | |
258 system may not accept this value in which case a different rate will be chosen. | |
259 This should generally be either the native sample rate of your sound card or an | |
260 integral divisor of it. Most modern sound cards have a native output rate that | |
261 is a multiple of 48000 Hz so the default setting should work well for most users. | |
262 | |
263 "buffer size" controls how large of a buffer uses for audio data. Smaller values | |
264 will reduce latency, but too small of a value can lead to dropouts. 512 works | |
265 well for me, but a higher or lower value may be more appropriate for your system. | |
266 | |
267 "lowpass_cutoff" controls the cutoff, or knee, frequency of the RC-style | |
268 low-pass filter. The default value of 3390 Hz is supposedly what is present in | |
269 at least some Genesis/Megadrive models. Other models reportedly use an even | |
270 lower value. | |
468 | 271 |
1014 | 272 Clocks |
273 ------ | |
274 | |
275 The clocks section contains settings that affect how fast things run. | |
276 | |
277 "m68k_divider" describes the relationsip between the master clock (which is | |
278 53693175 Hz for NTSC mode and 53203395 Hz for PAL mode). The default value of 7 | |
279 matches the real hardware. Set this to a lower number to overclock the 68000 | |
280 and set it to a higher number to underclock it. | |
281 | |
282 "max_cycles" controls how often the system is forced to synchronize all | |
283 hardware. BlastEm generally uses a sync on demand approach to synchronizing | |
284 components in the system. This can provide perfect synchronization for most | |
285 components, but since the Z80 can steal cycles from the 68000 at unpredictable | |
286 times 68000/Z80 synchronization is imperfect. The default value of 3420 | |
287 corresponds to the number of master clock cycles per line. Larger numbers may | |
288 produce a modest performance improvement whereas smaller numbers will improve | |
289 68000/Z80 synchronization. | |
290 | |
291 "speeds" controls the speed of the overall emulated console at different | |
292 presets. Preset 0 is the default speed and should normally be set to 100. The | |
293 other presets enable the slow/turbo mode functionality. | |
294 | |
295 UI | |
296 -- | |
297 | |
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
298 The UI section contains settings that affect the user interface. |
1014 | 299 |
300 "rom" determines the path of the Genesis/Megadrive ROM that implements the UI. | |
301 Relative paths will be loaded relative to the BlastEm executable. | |
302 | |
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
303 "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
|
304 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
|
305 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
|
306 |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
307 "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
|
308 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
|
309 |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
310 "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
|
311 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
|
312 |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
313 "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
|
314 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
|
315 $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
|
316 variables from the environment. |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
317 |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
318 Path Variables |
1014 | 319 -------------- |
320 | |
1353
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
321 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
|
322 in the previous section. |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
323 |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
324 $HOME The home directory of the current user. On most Unix variants, it |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
325 will be a subdirectory of /home. On Windows it will typically be a |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
326 subdirectory of C:\Users |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
327 $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
|
328 $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
|
329 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
|
330 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
|
331 $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
|
332 |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
333 System |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
334 ------ |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
335 |
52d9e3c36b4f
Update README to account for new config file options
Michael Pavone <pavone@retrodev.com>
parents:
1352
diff
changeset
|
336 "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
|
337 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
|
338 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
|
339 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
|
340 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
|
341 |
1014 | 342 "default_region" determines the console region that will be used when region |
343 detection fails and when there are multiple valid regions. The default of 'U' | |
344 specifies a 60Hz "foreign" console. | |
345 | |
468 | 346 Debugger |
347 -------- | |
348 | |
349 BlastEm has an integrated command-line debugger loosely based on GDB's | |
350 interface. The interface is very rough at the moment. Available commands in the | |
351 68K debugger are: | |
1066 | 352 b ADDRESS - Set a breakpoint at ADDRESS |
353 d BREAKPOINT - Delete a 68K breakpoint | |
354 co BREAKPOINT - Run a list of debugger commands each time | |
1014 | 355 BREAKPOINT is hit |
1066 | 356 a ADDRESS - Advance to address |
357 n - Advance to next instruction | |
358 o - Advance to next instruction ignoring branches to | |
359 lower addresses (good for breaking out of loops) | |
360 s - Advance to next instruction (follows bsr/jsr) | |
361 c - Continue | |
362 bt - Print a backtrace | |
363 p[/(x|X|d|c)] VALUE - Print a register or memory location | |
364 di[/(x|X|d|c)] VALUE - Print a register or memory location each time | |
365 a breakpoint is hit | |
366 vs - Print VDP sprite list | |
367 vr - Print VDP register info | |
368 zb ADDRESS - Set a Z80 breakpoint | |
369 zp[/(x|X|d|c)] VALUE - Display a Z80 value | |
370 q - Quit BlastEm | |
468 | 371 Available commands in the Z80 debugger are: |
1066 | 372 b ADDRESS - Set a breakpoint at ADDRESS |
373 de BREAKPOINT - Delete a Z80 breakpoint | |
374 a ADDRESS - Advance to address | |
375 n - Advance to next instruction | |
376 c - Continue | |
377 p[/(x|X|d|c)] VALUE - Print a register or memory location | |
378 di[/(x|X|d|c)] VALUE - Print a register or memory location each time | |
379 a breakpoint is hit | |
380 q - Quit BlastEm | |
468 | 381 |
382 The -d flag can be used to cause BlastEm to start in the debugger. | |
383 Alternatively, you can use the ui.enter_debugger action (mapped to the 'u' key | |
1014 | 384 by default) to enter the debugger while a game is running. To debug the menu |
385 ROM, use the -dm flag. | |
468 | 386 |
536 | 387 GDB Remote Debugging |
388 -------------------- | |
389 | |
390 In addition to the native debugger, BlastEm can also act as a GDB remote | |
391 debugging stub. To use this, you'll want to configure your Makefile to produce | |
392 both an ELF executable and a raw binary. Invoke an m68k-elf targeted gdb with | |
393 the ELF file. Once inside the gdb session, type: | |
394 | |
1066 | 395 target remote | BLASTEM_PATH/blastem ROM_FILE.bin -D |
536 | 396 |
397 where BLASTEM_PATH is the relative or absolute path to your BlastEm | |
398 installation and ROM_FILE.bin is the name of the raw binary for your program. | |
399 BlastEm will halt at the beginning of your program's entry point and return | |
400 control to GDB. This will allow you to set breakpoints before your code runs. | |
401 | |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
402 On Windows, the procedure is slightly different. First run |
1066 | 403 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
|
404 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
|
405 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
|
406 and type: |
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
407 |
1066 | 408 target remote :1234 |
808
2953708d02af
Update README, CHANGELOG and version string for 0.3.1
Michael Pavone <pavone@retrodev.com>
parents:
785
diff
changeset
|
409 |
536 | 410 Trace points and watch points are not currently supported. |
411 | |
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
|
412 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
|
413 -------------- |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
414 |
1f75614d7be8
Fixed an ommission in the CHANGELOG added basic description of extra utilities to README
Michael Pavone <pavone@retrodev.com>
parents:
808
diff
changeset
|
415 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
|
416 code. |
1066 | 417 |
418 dis - 68K disassembler | |
419 zdis - Z80 disassembler | |
420 vgmplay - Very basic VGM player | |
421 stateview - GST save state viewer | |
422 | |
1013 | 423 VSync |
424 ----- | |
425 | |
1014 | 426 This section includes information about using VSync with BlastEm. As mentioned |
427 above, the code is currently designed to only sync to audio and has some issues | |
428 with VSync as a result. That said, if your computer is fast enough and you | |
429 don't care about turbo mode, it can generally made to work. | |
430 | |
431 The native refresh rate of an NTSC Genesis is approximately 59.92 Hz which is | |
432 probably not the native refresh rate of your monitor. Fortunately, it is | |
433 most likely lower than your refresh rate. As long as this is true, VSync will | |
434 generally work as long as your computer is fast enough to cope with the time | |
435 lost waiting for VSync and the audio buffer is large enough to not run out of | |
436 samples during that delay. Latency will suffer a bit and you'll get a doubled | |
1352
90c9922b5430
Add description of overscan settings to README
Michael Pavone <pavone@retrodev.com>
parents:
1227
diff
changeset
|
437 frame every once and a while, but generally things will be fine. |
1014 | 438 |
439 If you enable VSync and you're getting audio dropouts, first try doubling the | |
440 audio buffer setting. If you still experience dropouts, it's possible your | |
441 computer is not fast enough or that your monitor's actual refresh rate is in | |
442 fact lower than that of the emualted console. Not much can be done about the | |
443 former (apart from disabling VSync), but the latter can be dealt with by | |
444 lowering the default speed slightly in the "clocks" section. | |
445 | |
446 A future release will support VSync in a less hacky fashion. | |
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
|
447 |
1066 | 448 Special Thanks |
449 -------------- | |
450 | |
451 My work has been made much easier by the contributions of those in the Genesis | |
452 community past and present. I'd like to thank the people below for their help. | |
453 | |
454 Nemesis - His work reverse engineering and documenting the VDP and | |
455 YM-2612 has saved me an immeasurable amount of time. I've | |
456 found both his sprite overflow test ROM and VDP FIFO | |
457 Testing ROM to be quite helpful. | |
458 | |
459 Charles MacDonald - While it hasn't been updated in a while, I still find his | |
460 VDP document to be my favorite reference. His Genesis | |
461 hardware document has also come in handy. | |
462 | |
463 Eke-Eke - Eke-Eke wrote a great document on the use of I2C EEPROM in | |
464 Genesis games and also left some useful very helpful | |
465 comments about problematic games in Genesis Plus GX | |
466 | |
467 Bart Trzynadlowski - His documents on the Genecyst save-state format and the | |
468 mapper used in Super Street Fighter 2 were definitely | |
469 appreciated. | |
470 | |
471 KanedaFR - Kaneda's SpritesMind forum is a great resource for the | |
472 Sega development community. | |
1354
34798ad9c570
Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents:
1353
diff
changeset
|
473 |
34798ad9c570
Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents:
1353
diff
changeset
|
474 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
|
475 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
|
476 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
|
477 assistance of Kabuto, Sik and Jorge in getting Overdrive 2 |
34798ad9c570
Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents:
1353
diff
changeset
|
478 to run properly in BlastEm. |
1066 | 479 |
480 I'd also like to thank the following people who have performed compatibility | |
481 testing or submitted helpful bug reports | |
482 | |
1354
34798ad9c570
Updated special thanks and version number listed in menu ROM
Michael Pavone <pavone@retrodev.com>
parents:
1353
diff
changeset
|
483 micky, Sasha, lol-frank, Sik, Tim Lawrence, ComradeOj, Vladikcomper |
1066 | 484 |
468 | 485 License |
486 ------- | |
487 | |
488 BlastEm is free software distributed under the terms of the GNU General Public | |
489 License version 3 or higher. This gives you the right to redistribute and/or | |
490 modify the program as long as you follow the terms of the license. See the file | |
491 COPYING for full license details. | |
492 | |
785
0e5f14d9a579
Prep for 0.3.0 release
Michael Pavone <pavone@retrodev.com>
parents:
536
diff
changeset
|
493 Binary releases of BlastEm are packaged with GLEW and SDL2 which have thier own |
0e5f14d9a579
Prep for 0.3.0 release
Michael Pavone <pavone@retrodev.com>
parents:
536
diff
changeset
|
494 licenses. See GLEW-LICENSE and SDL-LICENSE for details. |