README.osmesa.md

RetroArch's osmesa context

The osmesa context makes use of the OSMesa offscreen rendering library in order to provide a headless OpenGL context that does not require X or even a GPU running. Yes, it's a software renderer. The video contents can be read from an UNIX socket.

Building

To use the osmesa context, you must first recompile your RetroArch passing the --enable-osmesa switch to the configure script. If you don't see a line similar to the one bellow, it means that your Mesa install does not include OSMesa.

Checking presence of package osmesa ... 0

Configuring

RetroArch does not expose video context drivers in the user interface. To use the osmesa context you must set video_context_driver to osmesa in your RetroArch configuration file.

Using

To avoid issues, run your game from the command line instead of the menu. Once the game is up, you should see lines like these somewhere in your log/terminal:

[osmesa] Frame size is 960x720x4
[osmesa] Please connect to unix:/tmp/osmesa-retroarch.sock

The first line tells us the frame geometry and how many bytes per pixel are used. The format you must use in your media player changes according to the last argument:

 BPP | Format*
-----+--------
 2   | RGB565
 3   | RGB
 4   | RGBA

* The actual format name may be different in your media player of choice. Make sure to try variants of the same size like RGBA, BGRA, ARGB or ABGR.

The second line tells us the path of the UNIX socket. At the time of this writting, the path is hard-coded to /tmp/osmesa-retroarch.sock. You should configure you media player to load the raw frame data from this socket.

ffplay/ffmpeg example

ffplay -loglevel debug -f rawvideo -s 960x720 -pix_fmt rgba -i unix:/tmp/osmesa-retroarch.sock

Remember to change the -s and -pix_fmt parameters to match the frame information printed on the terminal. If you want to, you can also pass -framerate as ffplay defaults to 24.

If you want to record the video, just change ffplay to ffmpeg and append the appropriate output file options.

Known issues

• While the context driver itself has no problem handling resizes and context modification in general, it opens/closes the UNIX socket during set_video_mode and that causes playback issues in the media players. Not only because the file descriptor is now invalid but also because currently there is no way to tell the media player that the frame size changed.