Mercurial > repos > blastem
annotate README @ 1356:4d16c09210fd
Fix resampling code to deal with case in which output frequency is greater than the input frequency. Probably could stand to be improved, but at least it doesn't cause the emulator to deadlock
author | Michael Pavone <pavone@retrodev.com> |
---|---|
date | Thu, 11 May 2017 07:51:28 -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. |