ref: 1195ca910c393e542d6aa23035fa75719af1107e
dir: /sys/man/2/emu/
.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.