docs/glfbdev-driver.html

<HTML>

<TITLE>Mesa glFBDev Driver</TITLE>

<link rel="stylesheet" type="text/css" href="mesa.css"></head>

<BODY>

<center><H1>Mesa glFBDev Driver</H1></center>


<H1>1. Introduction</H1>

<p>
The GLFBDev driver interface allows one to do OpenGL rendering into a
framebuffer managed with the Linux's fbdev interface.
</p>

<p>
Basically, the programmer uses the fbdev functions to initialize the
graphics hardware and setup the framebuffer.
Then, using a calls to Mesa's glFBDev API functions, one can render
into the framebuffer with the OpenGL API functions.
</p>

<p>
Note, only software rendering is supported; there is no hardware
acceleration.
</p>


<p>
The GL/glfbdev.h header file defines the glFBDev interface.
</p>

<p>
The progs/fbdev/glfbdevtest.c demonstrates how to use the glFBDev interface.
</p>


<p>
For more information about fbdev, see the
<a href="http://www.tldp.org/HOWTO/Framebuffer-HOWTO.html" target="_parent">
Framebuffer Howto</a>
</p>
<p>
You will need at minimum, a framebuffer device, check /dev/fb0
</p>

<h1>2. Compilation</h1>

<p>
To compile Mesa with support for the glFBDev interface:
<pre>
      make realclean
      make linux-fbdev
</pre>

<p>
When compilation is finished look in progs/glfbdev/ for the glfbdevtest demo.
</p>
<h1>3. Permissions</h1>

<p>
Typically /dev/fb/0 is grouped to the video group.  It may be useful to add
your user to the video group so the demos will not have to be run as root.
To use fbdevglut with the prefered tty input, you should add the user to the
tty group as well
<p>

<h1>4. Using fbdevglut</h1>
Almost all of the programs in the progs directory use glut, and they compile with fbdevglut.

<p>
To compile the redbook sample programs:
<pre>
       cd progs/redbook
       make
</pre>
</p>
<p>glut features not supported:
<li>Overlays
<li>Subwindows
<li>Input devices other than Keyboard/Mouse
<li>No support for GLUT_MULTISAMPLE, GLUT_STEREO, or GLUT_LUMINANCE
<li>Cursor and Menu Support will flicker in GLUT_SINGLE mode

<p>Keyboard input is read by opening /dev/tty and reading keycodes in medium raw mode.
<p>Mouse input is read from env var MOUSE, or /dev/gpmdata and should be in ms3 format.
To forward data in this format to /dev/gpmdata, run gpm with the -Rms3 option.
<p> glutInit allows glut programs to pass parameters to the glut library, currently the
following options are supported for fbdevglut:
<p><li>-geometry widthxheight  --  This will force the resolution to be widthxheight instead of autodetecting.
The modes are read from /etc/fb.modes
<p><li>-bpp -- This will force the bitdepth to the one specified
<p><li>-vt -- This allows you to specify the virtual terminal to attach keyboard input to.  It is useful to specify when running inside screen.
<p><li>-mousespeed -- A floating point multiplication factor to increase mouse speed
<p><li>-nomouse -- Disable mouse support
<p><li>-nokeyboard -- Disable keyboard support (this will probably break mouse support as well)
<p><li>-stdin -- Use stdin for input instead of attaching to kbd in medium-raw mode.
This will make it impossible to detect keypresses like Shift+Tab, you will also need to specify -gpmmouse for mouse support.  This option can be used with a debugger, and it is possible to single step a program with gdb and set the FRAMEBUFFER environment variable to a different framebuffer for display.  The program will not be able to handle vt switching on it's own, so it will always display.
<p><li>-gpmmouse -- This will attempt to connect to the /dev/gpmctl socket using liblow
for mouse data.  Gpm does not provide this data when in graphics mode, so vt switching
will briefly display text.  This mode typically has no initial mouse delay.
<p><li>-- Ignore any additional arguments
<p>Notes:
<p>
1. The mouse pointer flickers in single buffering mode, as it must be rendered in software.  Hopefully in the future there will be a way to access hardware cursors in fbdev devices.
</p>
</body>
</html>