sys/man/2/emu

   1 .TH EMU 2
   2 .SH NAME
   3 initemu, regkeyfn, flushmouse, flushscreen, flushaudio, screenwipe \- graphical emulator-like software scaffolding
   4 .SH SYNOPSIS
   5 .nf
   6 .ft L
   7 #include <u.h>
   8 #include <libc.h>
   9 #include <emu.h>
  10 .PP
  11 .ta +\w'\fLvoid fP'u
  12 .B
  13 void    flushmouse(int discard);
  14 .PP
  15 .B
  16 void    flushscreen(void);
  17 .PP
  18 .B
  19 void    flushaudio(int (*fn)(void));
  20 .PP
  21 .B
  22 void    regkeyfn(Rune r, void (*fn)(void));
  23 .PP
  24 .B
  25 void    regkey(char *joyk, Rune r, int k);
  26 .PP
  27 .B
  28 void    initemu(int dx, int dy, int bpp, ulong chan,
  29 .B
  30            int dokey, void(*kproc)(void*));
  31 .SH DESCRIPTION
  32 .I Libemu
  33 implements common user interfaces for programs controlled
  34 with a joypad or a limited number of keys.
  35 .PP
  36 .B initemu
  37 initializes the display for the given internal screen size
  38 .B dx
  39 by
  40 .B dy
  41 and
  42 .B bpp
  43 bit depth.
  44 .B Chan
  45 is an
  46 .B Image
  47 pixel format descriptor to be used for an internal framebuffer (see
  48 .IR draw (2)).
  49 .PP
  50 If
  51 .B dokey
  52 is true,
  53 a keyboard process is started which sets a 64-bit wide bit vector for input keys.
  54 .PP
  55 Keys are set via
  56 .B regkey.
  57 Pressing the key corresponding to the
  58 .B r
  59 rune, or writing
  60 .B joyk
  61 to standard in will
  62 .L OR
  63 .B k
  64 with the key bit vector.
  65 .PP
  66 .B Regkeyfn
  67 registers an additional rune and a callback for the keyboard process.
  68 .PP
  69 Normally, a joypad process is also started, and parses standard input for key presses.
  70 If
  71 .B dokey
  72 is false, only the joypad process will be started.
  73 If
  74 .B kproc
  75 is a valid function pointer,
  76 it will be used for keyboard processing instead of the library-provided one,
  77 and no joypad process will be started.
  78 .PP
  79 .IP
  80 .EX
  81 .ta 6n
  82 uchar *pic;
  83 .EE
  84 .PP
  85 Once
  86 .B initemu
  87 is called, a framebuffer of the specifized size is allocated,
  88 and may be accessed via
  89 .BR pic .
  90 .L Libemu
  91 scales the framebuffer to fit the greatest multiple of the framebuffer's
  92 width in the window.
  93 The scaling is horizontal only and needs to be taken into account for drawing
  94 within the program.
  95 .PP
  96 Typically, mouse event handling is followed by drawing the final image from the
  97 internal framebuffer render and writing a constant amount of audio samples,
  98 thereby synchronizing the program's framerate to the audio writes.
  99 .IP
 100 .EX
 101 .ta 6n
 102 Mouse m;
 103 extern Mousectl *mc;
 104
 105 flushmouse(0);
 106 while(nbrecv(mc->c, &m) > 0){
 107         ...
 108 }
 109 flushscreen();
 110 flushaudio(audioout);
 111 .EE
 112 .PP
 113 Besides window resizing, mouse events are discarded by default.
 114 If
 115 .B discard
 116 is false
 117 .B flushmouse
 118 will let the user program handle mouse events prior to flushing the screen (see
 119 .BR event (2)).
 120 .PP
 121 .B Flushscreen
 122 handles re-scaling and re-allocating the buffers used, as well as drawing to
 123 the screen, either directly, or by duplicating pre-scaled scanlines.
 124 .SH SOURCE
 125 .B /sys/src/libemu
 126 .SH "SEE ALSO"
 127 .IR draw (2),
 128 .IR event (2)
 129 .SH BUGS
 130 The semantics for
 131 .B initemu
 132 input selection are confusing.
 133 .PP
 134 A greater effort should be made to simplify automatic scaling for user programs.
 135 .SH HISTORY
 136 .I Libemu
 137 first appeared in 9front in May, 2018.