LIBFB(3)

NAME
libfb - multiple device, generic frame buffer library

SYNOPSIS
#include <fb.h>

/* Generic frame buffer routines: */

FBIO *fb_open(fbfile, width, height)
char *fbfile;

int fb_close(fbp)
FBIO *fbp;

int fb_read(fbp, x, y, addr, count)
FBIO *fbp;
RGBpixel *addr;
long count;

int fb_write(fbp, x, y, addr, count)
FBIO *fbp;
RGBpixel *addr;
long count;

int fb_rmap(fbp, cmap)
FBIO *fbp;
ColorMap *cmap;

int fb_wmap(fbp, cmap)
FBIO *fbp;
ColorMap *cmap;

int fb_clear(fbp, colorp)
FBIO *fbp;
RGBpixel *colorp;

char *fb_gettype(fbp)
FBIO *fbp;

int fb_getwidth(fbp)
FBIO *fbp;

int fb_getheight(fbp)
FBIO *fbp;

/* Hardware specific frame buffer routines: */

int fb_cursor(fbp, mode, x, y)
FBIO *fbp;

int fb_scursor(fbp, mode, x, y)
FBIO *fbp;

int fb_setcursor(fbp, bits, xbits, ybits, xorig, yorig)
FBIO *fbp;
unsigned char bits[];
int xbits, ybits;
int xorig, yorig;

int fb_window(fbp, x, y)
FBIO *fbp;

int fb_zoom(fbp, x, y)
FBIO *fbp;

/* Buffered frame buffer I/O: */

int fb_ioinit(fbp)
FBIO *fbp;

int fb_seek(fbp, x, y)
FBIO *fbp;

void fb_tell(fbp, xp, yp)
FBIO *fbp;
int *xp, *yp;

int fb_rpixel(fbp, pixelp)
FBIO *fbp;
RGBpixel *pixelp;

int fb_wpixel(fbp, pixelp)
FBIO *fbp;
RGBpixel *pixelp;

int fb_flush(fbp)
FBIO *fbp;

void fb_log(format [, arg ] ... )
char *format;

DESCRIPTION
These routines are designed to provide a device-independent method of using frame buffers or files containing frame buffer images. The coordinate system used is first-quadrant (0..width-1, 0..height-1), with integer addressing. Translation to hardware coordinate systems is handled by the library.

This version of the library assumes that red, green, and blue intensities are described by unsigned 8-bit bytes in the range (0..255). The library interface uses arrays of RGBpixels, which is a typedef for an array of three unsigned chars (this was done to avoid structure padding). Note that a pointer to an RGBpixel is thus the name of the RGBpixel itself, i.e. no ampersand is needed.

The exact interpretation of color maps tends to be somewhat device specific. The three ColorMap arrays each have 256 entries of unsigned 16-bit values. In order to accomodate color maps with differing amounts of output resolution, the color map entries are fixed-point fractions in the range (0.0..1.0). In integer notation, the range is (0..65525). For devices with less than 16 bits of output from their color maps, the left-most portion of each entry is used.

Fb_open is used to open a frame buffer file fbfile. The file may be either the name of a supported frame buffer interface, referenced as "/dev/interface", or the name of a UNIX file. The routine will try to determine if the file opened was a real frame buffer by examining the name, and if so will perform whatever initialization actions are necessary. If the value of fbfile is NULL and the environment variable FB_FILE is set, then the value of FB_FILE is used; otherwise the default frame buffer device for the system is used. See below for more details. The width and height parameters specify the initial size of display desired. If these are zero the default sizes for that device will be used. On a successful open, the frame buffer I/O (FBIO) structure pointer is returned. This structure contains size you were actually given, as well as the maximum possible size for the selected device. A return of FBIO_NULL indicates failure.

Fb_close simply closes the frame buffer.

Fb_read reads count pixels from the frame buffer starting at the location specified by x and y, and places them at program memory address specified by addr. Fb_read returns the number of pixels actually read, or -1 on error.

Fb_write writes count pixels from program address addr into the frame buffer starting at the location specified by x and y. Fb_write returns the number of pixels actually written, or -1 on error.

Fb_rmap reads in the color map from the frame buffer and leaves at the location pointed to by cmap.

Fb_wmap writes the color map pointed to by cmap into the frame buffer. If the value of cmap is NULL then a linear color map is used as the default.

Fb_clear erases the frame buffer by setting all pixels to the given color. If the color pointer is NULL, black will be used. On a UNIX file, this entails writing the entire file, which is an expensive operation, whereas on most frame buffer displays this can be done in less than a second by a special command.

Fb_gettype returns a pointer to a string describing the frame buffer specified by the FBIO pointer.

Fb_getwidth and Fb_getheight returns the current size of the FBIO frame buffer.

The following routines work in conjunction with those described above to provide functions which only apply if the frame buffer file is actually a hardware frame buffer display.

Fb_cursor places the cursor at the image space coordinates given by x and y. If the mode is non-zero, the cursor is made visible, and if mode is zero, the cursor is turned off.

Fb_scursor is the same as fb_cursor except that it places the cursor at the screen space coordinates given by x and y.

Fb_setcursor allows the user to set the bitmap used to represent the cursor, thereby changing the cursor shape. This is not necessarily supported by all hardware. The argument bits is a pointer to an array of unsigned chars containing the bits of the cursor. The arguments xbits and ybits specify the size of the cursor bitmap. The number of bytes in the bits array will be the width rounded up to a mutiple of eight (so that the cursor "scanlines" are byte aligned) times the height. bits[0] is the lower left corner, bits[1] is to the right of it, etc. The next line of the bits array goes above the current one. Within a byte the most significant bit is the leftmost. The values xorig and yorig specify which bit in the bitmap actually gets placed at the location specified in the cursor move routines. Again, a first quadrant coordinate system is used.

Fb_window sets the frame buffer window center position to the image space coordinates given by x and y. This command is usually used in conjunction with the fb_zoom routine.

Fb_zoom sets the zoom factor for the X coordinate to x and the zoom factor for the Y coordinate to y. Zooming is generally done by pixel replication in hardware.

The following routines work in conjunction with those described above to provide buffered reading and writing of frame buffer images either to a real frame buffer or a UNIX file. The routines use a simple paging strategy to hold ``bands'' of the image in core. Since horizontal bands are buffered, the ideal motion is to scan left to right, then bottom to top.

Fb_ioinit should be called before using any of the other buffered I/O routines and repeated whenever the frame buffer is reopened.

Fb_seek is used to position the current read/write pointer to the location to the next position to be read or written. It is not necessary to do a fb_seek after every read or write since both fb_rpixel and fb_wpixel imply an automatic move to the next pixel. If you read or write the last pixel on a scan line, the pointer will automatically move to the beginning of the following scan line.

Fb_tell returns the current location of the read write pointer in terms of (X,Y) coordinates on the frame buffer. The X and Y values are returned into the integers pointed to by xp and yp.

Fb_rpixel reads the pixel at the current frame buffer location and returns it into the location specifed by pixelp.

Fb_wpixel writes the pixel pointed to by pixelp at the current frame buffer location.

Fb_flush caused any current buffered frame buffer pages to be written out. Unnecessary writes are avoided by the use of page reference bits.

The following is a printing routine which this library uses to indicate errors.

Fb_log will convert, format and print its args under control of format to the standard error output. For more detailed information on the specification of the control string, see printf(3S). This function may be supplied by the application if different behavior is desired.

FB_FILE DEVICES
The following devices are supported by the library; not all may be available on any given system. New device support can be incorporated by the addition of a single module to the library.

/dev/debug[num]
    The "/dev/debug" interface prints one line to logs each call to the frame buffer library.
    num is a bitvector indicating the levels of verbosity of the output. See fb.h for the bit definitions.

filename
    Disk file interface

/dev/ik[num][opt]
    Adage RDS-3000 ("Ikonas")
    Num indicates the device number.
    Opt is a single character which indicates optional mode modification. The letter ``v'' is to select NTSC video with internal sync. The letter ``e'' is to select NTSC video with external sync. The letter ``n'' is to select no frame-buffer controller (FBC) re-init upon open; the default is to reprogram the FBC on each open.

/dev/sgi[num]
    Silicon Graphics IRIS Workstation
    When the display is running the window-manager MEX, the default is to open a window in 12-bit mode, with RGB converted to a 10x10x10 color-cube approximation. A non-zero num will select a dynamically allocated colormap, which is slower but sometimes of higher quality. When MEX is not running, the full 24-bits of color are used on systems with that deep a display. Regardless of mode, the full 24-bits of color are stored in a shared memory segment, allowing it to be operated on in the "frame buffer" in MEX mode without loss of color accuracy when the image is read back. To release the shared memory segment, open /dev/sgi99.

/dev/rat
    RasterTek 1/80 (untested) /dev/sun Sun PixWin interface. On monochrome displays, a dither pattern is used to create the impression of shading. On 8-bit color displays, a simple 3x3x2 color-cube approximation is used. At present, there is no ability to read back pixels from the Sun display, making it less useful for serious image manipulation, but being able to ``brouse'' through images even on a monochrome workstation makes this still a very useful capability.

hostname:[devicename]
    TCP-based network links to a remote framebuffer, where devicename is any from this list, for example, fictitious.brlcad.org:/dev/ik0 or fictitious.brlcad.org:/dev/sgi. A hostname with a null devicename will select the default display device on that host. If explicitly specifying a remote device, be careful not to omit the colon between the host and device name, or you will be specifying a local disk file as the result. Note that for security reasons, it is not permitted to access a disk file via the remote interface.

EXAMPLE
Libfb can be loaded with any C program:

    $ /bin/cc program.c -lfb -l<system-library...>

where <system-library> denotes specific libraries necesary on a particular machine. All machines with networking will require the "-lpkg" option. Machines which support the X Windows(tm) system will require the "-lX11" option. In addition, the following table lists architectures and libraries above and beyond the pkg and X11 libraries.

 Architecture Libraries
 SGI 3030 -lbsd -ldbm -lgl2
 SGI 4d -lgl_s
 Sun -lsuntool -lsunwindow -lpixrect
 Sun+TS -lsuntool -lsunwindow -lpixrect -lgds

FILES
fb.h
/usr/brl/lib/libfb.a

SEE ALSO
fbhelp(1), brlcad(1).

RETURN VALUES
fb_close, fb_write, fb_read, fb_wmap, fb_rmap, fb_clear, fb_cursor, fb_scursor, fb_setcursor, fb_window, fb_zoom, fb_ioinit, fb_seek, fb_wpixel, fb_rpixel and fb_flush return -1 to indicate failure. Fb_open returns FBIO_NULL to indicate failure, and a non-null FBIO structure pointer upon success. fb_read, and fb_write return the number of pixels actually read or written. fb_gettype returns a pointer to a NULL terminated description string.

BUGS
Vertical scanning will incur the most overhead, making it almost impractical. Due to the way memory is organized in frame buffers and UNIX files, vertical scanning will never be easy unless the image can be rotated.

BUG REPORTS
Reports of bugs or problems should be submitted via electronic mail to <devs@brlcad.org>.