comparison README @ 1013:f2f983e262e2

WIP README updates
author Michael Pavone <pavone@retrodev.com>
date Mon, 02 May 2016 00:31:44 -0700
parents 1f75614d7be8
children ef923c4b8977
comparison
equal deleted inserted replaced
1012:35ae24bf4ba0 1013:f2f983e262e2
1 BlastEm 0.3.1 1 BlastEm 0.4.0
2 ------------- 2 -------------
3 3
4 Installation 4 Installation
5 ------------ 5 ------------
6 6
10 environment variable. 10 environment variable.
11 11
12 Usage 12 Usage
13 ----- 13 -----
14 14
15 BlastEm does not have much of a GUI at the moment and expects a filename to be 15 This version of BlastEm has an experimental GUI that is implemented as a Genesis
16 passed to it at startup. You can do this by either running it from the command 16 ROM running inside the emulator. This UI can be operated with either a mouse or
17 line or associating it with a file type. To get a list of supported command 17 the first emulated gamepad. By default, both the keyboard and the first game
18 line options on Linux or OSX type: 18 controller are mapped to said gamepad. For more information on bindings see the
19 Bindings section.
20
21
22 Some operations are currently only supported through the command line. To get a
23 list of supported command line options on Linux or OSX type:
19 24
20 ./blastem -h 25 ./blastem -h
21 26
22 From within your BlastEm directory. On Windows type: 27 From within your BlastEm directory. On Windows type:
23 28
43 enter and esc respectively. Other keys that do not produce characters are not 48 enter and esc respectively. Other keys that do not produce characters are not
44 yet supported. 49 yet supported.
45 50
46 The pads subsection is used to map gamepads and joysticks. Analog axes are not 51 The pads subsection is used to map gamepads and joysticks. Analog axes are not
47 currently supported. An example configuration is provided in default.cfg to map 52 currently supported. An example configuration is provided in default.cfg to map
48 SDL joystick 0 to the second controller. 53 SDL joystick 0 to the first controller and SDL joystick 1 to the second
54 controller. The button assignments there work well for a 360 controller (at
55 least on Linux, it's possible the physical button to button number is different
56 on other operating systems).
57
58 The mice subsection is used to map mice to emulated Mega/Sega mice. The default
59 configuration maps both the first and second host mice to the first emulated
60 mouse. This should not need modification for most users.
61
62 One special mapping deserves a mention. By default, the 'r' key is mapped to
63 ui.release_mouse. When operating in windowed mode the mouse has a capture
64 behavior. Mouse events are ignored until you click in the window. The mouse
65 will then be "captured" and the cursor will be both made invisible and locked
66 to the window. The ui.release_mouse binding releases the mouse so it can be
67 used normally.
68
69 IO
70 --
71
72 This section controls which peripherals are attached to the emulated console.
73 IO assignments can be overridden by the ROM database when appropriate. For
74 instance, games with mouse support can automatically use the mouse and games
75 that only support 3-button pads can automatically force an appropriate pad.
76 Unforunately, the ROM database is not yet exhaustive so manual configuration
77 may be needed here in some cases.
49 78
50 Video 79 Video
51 ----- 80 -----
52 81
53 The video section currently has three settings: "width", "vertex_shader" and 82 The video section contains settings that affect the visual output of BlastEm.
54 "fragment_shader". "width" sets the width of the window in pixels. Height is 83
55 calculated from this value. Both width and height can be overridden from the 84 "width" is used to control the window size when not in fullscreen mode. The
56 command line. "vertex_shader" and "fragment_shader" control which GLSL shader 85 height of the window is calculated from this value. Both width and height can
57 files are used for rendering the display when in Open GL rendering mode. 86 be overridden from the command line.
58 Shaders can be used to implement graphical filters and other effects. 87
88 "vertex_shader" and "fragment_shader" define the GLSL shader program that
89 produces the final image for each frame. Shaders can be used to add various
90 visual effects or enhancements. Currently BlastEm only ships with the default
91 shader. If you write your own shaders, place them in
92 $HOME/.config/blastem/shaders and then specify the basename of the new shader
93 files in the "vertex_shader" and "fragment_shader" config options. Note that
94 shaders are not available in the SDL fallback renderer.
95
96 "scanlines" controls whether there is any emulation of the gaps between display
97 lines that are present when driving a CRT television with a 240p signal. This
98 emulation is very basic at the moment so this option is off by default.
99
100 "vsync" controls whether the drawing of frames is synchronized to the monitor
101 refresh rate. Valid values for this setting are "off", "on" and "tear". The
102 latter will attempt to use the "late tear" option if it's available and normal
103 vsync otherwise. Currently it's recommended to leave this at the default of
104 "off" as BlastEm synchronizes to audio and does not yet have the necessary code
105 to fully handle conflicts between the audio rate and monitor refresh rate.
106 Additionally, the "turbo" feature does not function properly with vsync
107 enabled. These issues will be addressed in a future release. If you wish to use
108 vsync, please see the VSync section at the bottom of the README.
59 109
60 Audio 110 Audio
61 ----- 111 -----
62 112
63 The audio section has two config values: rate and buffer. rate selects the 113 The audio section contains settings that affect the audio output of BlastEm
64 sample rate and buffer sets the size of the output buffer in samples. 512 is 114
65 generally a good value, but if you're experiencing audio dropouts you might 115 "rate" selects the preferred sample rate for audio output. Your operating
66 want to increase it to 1024. 116 system may not accept this value in which case a different rate will be chosen.
117 This should generally be either the native sample rate of your sound card or an
118 integral divisor of it. Most modern sound cards have a native output rate that
119 is a multiple of 48000 Hz so the default setting should work well for most users.
120
121 "buffer size" controls how large of a buffer uses for audio data. Smaller values
122 will reduce latency, but too small of a value can lead to dropouts. 512 works
123 well for me, but a higher or lower value may be more appropriate for your system.
124
125 "lowpass_cutoff" controls the cutoff, or knee, frequency of the RC-style
126 low-pass filter. The default value of 3390 Hz is supposedly what is present in
127 at least some Genesis/Megadrive models. Other models reportedly use an even
128 lower value.
67 129
68 Debugger 130 Debugger
69 -------- 131 --------
70 132
71 BlastEm has an integrated command-line debugger loosely based on GDB's 133 BlastEm has an integrated command-line debugger loosely based on GDB's
72 interface. The interface is very rough at the moment. Available commands in the 134 interface. The interface is very rough at the moment. Available commands in the
73 68K debugger are: 135 68K debugger are:
74 b ADDRESS - Set a breakpoint at ADDRESS 136 b ADDRESS - Set a breakpoint at ADDRESS
75 d BREAKPOINT - Delete a 68K breakpoint 137 d BREAKPOINT - Delete a 68K breakpoint
138 di[/(x|X|d|c)] VALUE - Print a register or memory location when a
139 breakpoint is hit
140 co BREAKPOINT - Run a list of debugger commands when BREAKPOINT is
141 hit
76 a ADDRESS - Advance to address 142 a ADDRESS - Advance to address
77 n - Advance to next instruction 143 n - Advance to next instruction
78 o - Advance to next instruction ignoring branches to 144 o - Advance to next instruction ignoring branches to
79 lower addresses (good for breaking out of loops) 145 lower addresses (good for breaking out of loops)
80 s - Advance to next instruction (follows bsr/jsr) 146 s - Advance to next instruction (follows bsr/jsr)
133 199
134 dis - 68K disassembler 200 dis - 68K disassembler
135 zdis - Z80 disassembler 201 zdis - Z80 disassembler
136 vgmplay - Very basic VGM player 202 vgmplay - Very basic VGM player
137 stateview - GST save state viewer 203 stateview - GST save state viewer
204
205 VSync
206 -----
207
208 This section includes information
138 209
139 License 210 License
140 ------- 211 -------
141 212
142 BlastEm is free software distributed under the terms of the GNU General Public 213 BlastEm is free software distributed under the terms of the GNU General Public