FBDUMP README
-------------

fbdump is a simple tool that captures the contents of the visible portion of
the Linux framebuffer device and writes it to the standard output as a PPM
file. In other words, it takes a screenshot of anything running on the
framebuffer.

fbdump was inspired by an even simpler program I came across ages ago called
fbsnap, which I believe was written by Gerd Knorr (although no author is
mentioned in the source code of that program, so I could be wrong). fbdump
bears little relationship to fbsnap, however, and is generally much more
useful. It supports framebuffers employing a greater variety of pixel and
colour models, works (should work?) on big- and little-endian architectures,
and is reasonably quick (although reading from video memory is never going to
be super fast).

I first wrote fbdump many moons ago when I needed a quick and simple way to
grab lots of images from the framebuffer. As most of you will probably know,
although it's possible to do a raw framebuffer dump by performing a simple
cat /dev/fb0 or similar -- depending on what pixel format and colour model
your framebuffer uses -- the results are not always particularly useful. With
fbdump, on the other hand, you always get a nice, portable, 24-bit, true-
colour image -- since it takes care of any pixel format or colour-space
conversion required (at least for formats it supports).

Why does fbdump save the image as a PPM -- rather than, for instance, a PNG --
you might ask? Well, a PPM is cheap to write out and doesn't require linking
against any external libraries to do so. On the x86 architecture, fbdump
currently compiles down to a miniscule 8K executable once stripped -- and has
no dependencies other than the standard C library. Having said that, I may get
around to adding support for PNG at some point. It's not strictly necessary,
though, because with the NetPBM package (see http://netpbm.sourceforge.net/)
it's easy to convert PPMs into something more useful. For example, you can do
something like

fbdump | pnmtopng > grab.png

to output the framebuffer as a PNG. PPMs can also be read directly by most open
source image processing packages, such as the Gimp and ImageMagick.


Compiling
---------

A configure script is provided, so to build fbdump just follow the usual
./configure and make incantation. There are no unusual build requirements.

The only extra configure option supported is --disable-vga16fb, which will
cause fbdump to be built without support for the vga16fb framebuffer driver.
This option should be set appropriately, automatically, according to your
target architecture. If you have problems and are building for CPUs other than
x86, then try manually disabling the vga16fb support.


Usage
-----

fbdump currently supports the following arguments:

-fb <string>	 Specifies the framebuffer device to grab from is <string>
-vt <num>	 Bring virtual terminal number <num> to the foreground before
    		 grabbing (and return to the current terminal afterwards).
-delay <num>	 Delay <num> seconds after switching, but before grabbing.

If the -fb option is not provided, fbdump defaults to grabbing from the
device /dev/fb0. You can also specify the framebuffer via the environment
variable FRAMEBUFFER (a value supplied with -fb switch on the command line
will override this). For example:

FRAMEBUFFER=/dev/fb1 fbdump >out.ppm

The -vt option effectively allows grabbing from another virtual terminal
other than the one that fbdump itself is running in. This is a useful feature,
since it allows you to easyily grab from an application which takes over the
entire framebuffer, without requiring you to log-in remotely. If a valid VT
number is supplied with the -vt option, then fbdump will detach itself from
the terminal it's running in (before switching VTs). This is necessary
because, otherwise, the framebuffer accesses would still be directed at
fbdump's VT rather than the new foreground terminal.

The -delay option is particularly useful if you are on a large and deep
framebuffer and you want to switch VTs with the -vt option. A suitable delay
will give the application running in the target VT enough time to redraw itself
before fbdump starts grabbing.

When grabbing, fbdump currently supports only packed-pixel framebuffer formats
and the vga16 framebuffer. You will need root permission to grab from a vga16
framebuffer, but with other devices you just need permission to read from the
framebuffer device (/dev/fb0 or what ever that happens to be).

fbdump understands the following packed-pixel colour models:

Colour model    Depths
------------    -----
Pseudo-colour   8
Direct-colour   15,16,24,32
True-colour     15,16,24,32

This should cover majority of what most people use. If you need support for
a different pixel format, please get in touch.

fbdump should work on big- or little-endian hardware. It has been tested
on a variety of x86, x86-64 and PPC systems and has proved reliable.
However, fbdump makes a number of assumptions that may or may not work
in all cases. For example, fbdump assumes that the endian-ness of the
framebuffer is the same as the endian-ness of the host CPU. In short,
problems may occur. If they do, let me know.

Send bug reports and suggestions to:

Richard Drummond
mailto:evilrich@rcdrummond.net
