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