Varvara implementation for the Linux Framebuffer.

quickstart

$ make
./uxn-lfb <ROM>

keybindings

F1 toggle screen rotation F2 emits debugging info F4 quits the emulator. F6 takes a screenshot in TGA format (screenshot.tga by default)

You can use Imagemagick to convert screenshots to other formats:

convert screenshot.tga screenshot.png

command-line options

$ uxn-lfb -h
usage: ./uxn-lfb [options] ROM [args]
options:
 -d      enable debug logging
 -h      show this message and exit
 -r N    rotate screen (1: 90 deg cw, 2: 180, 3: 90 deg ccw )
 -v      show version information and exit
 -b      show border around ROM screen
 -B      hide border around ROM screen
ROM is a Varvara rom file. The [args] are passed to the rom.

requirements

Code assumes modern Linux header files and a reasonable libc. No other dependencies.

Must be run directly in a Linux Console (not from X or Wayland).

Your user needs to have the right permissions to access the framebuffer and input devices.

Usually this means being in the video and input groups:

$ id
uid=1000(d6) gid=1000(d6) groups=4(adm),5(tty),7(lp),10(wheel),11(floppy),18(audio),19(cdrom),20(dialout),23(input),27(video),28(netdev),35(games),100(users),1000(d6)

(If you modify /etc/group to add your user to these groups you will usually need to log out and log back in to see the changes.)

debugging devices and events

To inspect your input devices, try installing evtest.

apk add evtest     # alpine
apt install evtest # debian, mint, ubuntu, etc.
pacman -S evtest   # arch, manjaro, etc.
dnf install evtest # fedora, etc.

Alternately you can use the included Python program:

$ python devscan.py

To debug screen drawing problems run detect and send me the output:

$ make detect
$ detect | tee OUTPUT   # send me the OUTPUT

To debug missing input events try the demo program:

$ make demo
$ ./demo # Ctrl-X to quit, or wait 10 seconds

If you have a keyboard, mouse, touchpad, or controller that doesn't work, please send me the output of evtest /dev/input/eventXYZ as well as the output of python devscan.py and ./demo if relevant.

status

The emulator was ported from uxn11 and should support any ROM that runs there.

The emulator does not do any filesystem sandboxing.

It seems to run fine on systems while X/Wayland are running but there are probably bugs related to how these systems interact, especially if you switch back to X/Wayland while uxn-lfb is still running.

WARNING!

This emulator is still pretty new and the Linux VT system is somewhat complicated. There's a chance that emulator bugs will require you to use SSH to kill the process, or even to need to reboot the system. Consider avoiding leaving important work unsaved while running it.

known issues

The mouse and touchpad don't feel perfect, especially on slow computers where the mouse vector is doing a lot of work. We have a tunable parameter (dev_input_delay) which trades higher latency for increased smoothness and another (dev_input_min_pressure) which controls touchpad sensitivity.

Switching virtual consoles requires uxn-lfb to redraw every pixel when resuming. On older machines this can be perceived as a small delay.

If you manage to launch uxn-lfb while viewing the "wrong" virtual console strange things can happen. To use F4 to quit you need to be on the virtual console where you launched the process, even if that is not the one displaying the ROM. This race condition needs fixing.

Since we are using raw input devices there is currently no support for alternate keyboard layouts or compose characters. Patches welcome, but consider talking to me first before you attempt this. Relatedly, we don't currently support the CAPS LOCK key.

On slower devices we can fall behind when someone is typing quickly or when there's mouse movement. I think this has to do with the way we are using select -- we are only "seeing" one input event per loop through the select. I have made some progress fixing this but it's possible some ROMs may still have issues.

goals

Support Varvara (System, Console, Controller, Mouse, File, DateTime)
Detect Linux input devices (keyboard, controller, touchpad, mouse)
Subprocess support in console device
Virtual console switching
Support screen rotation
Changing rotation dynamically
Soft restarting of ROMs
Taking screenshots (TGA format)
Improve mouse/touchpad on slower computers
Optimize framebuffer perf
(stretch) CLI mode (input devices + text mode)
(stretch) Audio device using ALSA
(stretch) NetBSD Framebuffer support

credits

uxn-lfb was created by Eiríkr Åsheim.

uxn11 was created by Devine Lu Linvega with help from Andrew Alderwick, Andrew Richards, Eiríkr Åsheim, and Sigrid Solveig Haflínudóttir.

There's also a much older uxnfb project.