add libemu

move redundant code from emulators to a common library

3 files changed, 145 insertions, 17 deletions

diff --git a/sys/man/1/nintendo b/sys/man/1/nintendo
index 89696f18e..b1ea5cc7c 100644
--- a/sys/man/1/nintendo
+++ b/sys/man/1/nintendo
@@ -4,7 +4,7 @@ gb, gba, nes, snes \- emulators
 .SH SYNOPSIS
 .B games/gb
 [
-.B -23acdT
+.B -acdT
 ]
 [
 .B -C
@@ -14,7 +14,7 @@ gb, gba, nes, snes \- emulators
 .br
 .B games/gba
 [
-.B -23aT
+.B -aT
 ] [
 .B -b
 .I biosfile
@@ -26,13 +26,13 @@ gb, gba, nes, snes \- emulators
 .br
 .B games/nes
 [
-.B -23aos
+.B -aos
 ]
 .I romfile
 .br
 .B games/snes
 [
-.B -23ahmsT
+.B -ahmsT
 ]
 .I romfile
 .SH DESCRIPTION
@@ -43,7 +43,7 @@ and
 .I snes
 are emulators for the Nintendo Game Boy and Game Boy Color (GB and GBC), Nintendo Game Boy Advance (GBA), Nintendo Entertainment System (NES), and Super Nintendo Entertainment System (SNES).
 They execute the romfile given as an argument.
-The \fBz\fR, \fBx\fR, \fBa\fR, \fBs\fR, return and shift keys correspond to B, A, Y, X, Start and Select, respectively.
+The \fBz\fR, \fBx\fR, \fBa\fR, \fBs\fR, \fBq\fR, \fBw\fRreturn and shift keys correspond to B, A, Y, X, L1, L2, Start and Select, respectively.
 Other keys:
 .TP
 F5
@@ -60,14 +60,8 @@ Exit the emulator.
 .PP
 Command line options:
 .TP
-.B -2 -3
-Scale the screen by the given factor.
-.TP
 .B -a
 Enable audio output.
-.TP
-.B -T
-Display percentage of how fast the emulator is running relative to a real console.
 .PP
 .B gb
 options:
diff --git a/sys/man/1/sega b/sys/man/1/sega
index 382c34bf9..5b0714b35 100644
--- a/sys/man/1/sega
+++ b/sys/man/1/sega
@@ -4,14 +4,14 @@ md \- emulator
 .SH SYNOPSIS
 .B games/md
 [
-.B -23a
+.B -a
 ]
 .I romfile
 .SH DESCRIPTION
 .I Md
 is an emulator for the Sega Megadrive/Genesis.
 It executes the romfile given as an argument.
-The \fBz\fR, \fBx\fR, \fBc\fR, return and shift keys correspond to A, B, C, Start and Select, respectively.
+The \fBz\fR, \fBx\fR, \fBa\fR, return and shift keys correspond to A, B, C, Start and Select, respectively.
 Other keys:
 .TP
 Esc
@@ -22,9 +22,6 @@ Exit the emulator.
 .PP
 Command line options:
 .TP
-.B -2 -3
-Scale the screen by the given factor.
-.TP
 .B -a
 Enable audio output.
 .SH SOURCE
@@ -33,4 +30,4 @@ Enable audio output.
 Probably!
 .SH HISTORY
 .I Md
-first appeared in 9front (May, 2014).
+first appeared in 9front (November, 2014).
diff --git a/sys/man/2/emu b/sys/man/2/emu
new file mode 100644
index 000000000..68026416b
--- /dev/null
+++ b/sys/man/2/emu
@@ -0,0 +1,137 @@
+.TH EMU 2
+.SH NAME
+initemu, regkeyfn, flushmouse, flushscreen, flushaudio, screenwipe \- graphical emulator-like software scaffolding
+.SH SYNOPSIS
+.nf
+.ft L
+#include <u.h>
+#include <libc.h>
+#include <emu.h>
+.PP
+.ta +\w'\fLvoid fP'u
+.B
+void	flushmouse(int discard);
+.PP
+.B
+void	flushscreen(void);
+.PP
+.B
+void	flushaudio(int (*fn)(void));
+.PP
+.B
+void	regkeyfn(Rune r, void (*fn)(void));
+.PP
+.B
+void	regkey(char *joyk, Rune r, int k);
+.PP
+.B
+void	initemu(int dx, int dy, int bpp, ulong chan,
+.B
+	   int dokey, void(*kproc)(void*));
+.SH DESCRIPTION
+.I Libemu
+implements common user interfaces for programs controlled
+with a joypad or a limited number of keys.
+.PP
+.B initemu
+initializes the display for the given internal screen size
+.B dx
+by
+.B dy
+and
+.B bpp
+bit depth.
+.B Chan
+is an
+.B Image
+pixel format descriptor to be used for an internal framebuffer (see
+.IR draw (2)).
+.PP
+If
+.B dokey
+is true,
+a keyboard process is started which sets a 64-bit wide bit vector for input keys.
+.PP
+Keys are set via
+.B regkey.
+Pressing the key corresponding to the
+.B r
+rune, or writing
+.B joyk
+to standard in will
+.L OR
+.B k
+with the key bit vector.
+.PP
+.B Regkeyfn
+registers an additional rune and a callback for the keyboard process.
+.PP
+Normally, a joypad process is also started, and parses standard input for key presses.
+If
+.B dokey
+is false, only the joypad process will be started.
+If
+.B kproc
+is a valid function pointer,
+it will be used for keyboard processing instead of the library-provided one,
+and no joypad process will be started.
+.PP
+.IP
+.EX
+.ta 6n
+uchar *pic;
+.EE
+.PP
+Once
+.B initemu
+is called, a framebuffer of the specifized size is allocated,
+and may be accessed via
+.BR pic .
+.L Libemu
+scales the framebuffer to fit the greatest multiple of the framebuffer's
+width in the window.
+The scaling is horizontal only and needs to be taken into account for drawing
+within the program.
+.PP
+Typically, mouse event handling is followed by drawing the final image from the
+internal framebuffer render and writing a constant amount of audio samples,
+thereby synchronizing the program's framerate to the audio writes.
+.IP
+.EX
+.ta 6n
+Mouse m;
+extern Mousectl *mc;
+
+flushmouse(0);
+while(nbrecv(mc->c, &m) > 0){
+	...
+}
+flushscreen();
+flushaudio(audioout);
+.EE
+.PP
+Besides window resizing, mouse events are discarded by default.
+If
+.B discard
+is false
+.B flushmouse
+will let the user program handle mouse events prior to flushing the screen (see 
+.BR event (2)).
+.PP
+.B Flushscreen
+handles re-scaling and re-allocating the buffers used, as well as drawing to
+the screen, either directly, or by duplicating pre-scaled scanlines.
+.SH SOURCE
+.B /sys/src/libemu
+.SH "SEE ALSO"
+.IR draw (2),
+.IR event (2)
+.SH BUGS
+The semantics for
+.B initemu
+input selection are confusing.
+.PP
+A greater effort should be made to simplify automatic scaling for user programs.
+.SH HISTORY
+.I Libemu
+first appeared in 9front in May, 2018.