LIBFB(3V)

NAME
libfb - generic frame buffer library

SYNOPSIS
#include ``/vld/include/fb.h''

/* Generic frame buffer routines: */

int fbopen(fbfile, mode);
char *fbfile;

int fbclose(fbfd);

int fbread(x, y, addr, count);
Pixel *addr;
long count;

int fbwrite(x, y, addr, count);
Pixel *addr;
long count;

int fb_rmap(cmap);
ColorMap *cmap;

int fb_wmap(cmap);
ColorMap *cmap;

int fbclear();

int fbgettype();

int fbgetsize();

void fbsetsize(size);

void fbsetbackground(pixelp);
Pixel *pixelp;

/* Hardware specific frame buffer routines: */

int fbcursor(mode, x, y);

int fbscursor(mode, x, y);

int fbsetcursor(bitmap);
long bitmap[32];

int fbwindow(x, y);

int fbzoom(x, y);

/* Buffered frame buffer I/O: */

void fbioinit();

int fbseek(x, y);

void fbtell(xp, yp);
int *xp, *yp;

int fbrpixel(pp);
Pixel *pp;

int fbwpixel(pp);
Pixel *pp;

int fbflush();

DESCRIPTION
These routines are designed to provide a device-independent method of using frame buffers or files containing frame buffer images.

Fbopen is used to open the frame buffer file fbfile. The file may be either a frame buffer, or 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. The mode flag value is either APPEND or CREATE defined in fb.h. If the mode CREATE is used and fbfile is a UNIX file, then the file will be created if necessary. If the APPEND flag is used and the file does not exist, fbopen will fail. If the value of fbfile is NULL and the environment variable FB_FILE is set, then its value is used; otherwise a default frame buffer device is used. The frame buffer file descriptor is returned.

Fbclose simply closes the frame buffer file descriptor.

Fbread 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.

Fbwrite writes count pixels from program address addr into the frame buffer starting at the location specified by x and y.

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.

Fbclear tries to erase the frame buffer and set all pixels to the background color. The default is black. 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.

Fbgettype returns the type of the currently open frame buffer. The valid values are defined in fb.h.

Fbsetsize should be used to specify the size of the frame buffer in pixels per side. Typically this is either 512 or 1024 (the frame buffer is assumed to be square). Fbsetsize should be used before fbopen if the frame buffer size is not the default, 512. Fbgetsize returns the current size of the frame buffer. Regardless of whether a high or low resolution device name was provided to fbopen, that device name will be altered to reflect the current frame buffer size.

Fbsetbackground sets the desired background color as specified by the pixel pointed to by pixelp. This feature may not be fully supported depending on available hardware. Fbclear will attempt to clear the frame buffer to this color.

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.

Fbcursor 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.

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

Fbsetcursor 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 bitmap is a pointer to an array of 32 32-bit integers.

Fbwindow 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 fbzoom routine.

Fbzoom sets the zoom factor for the X coordinate to x and the zoom factor for the Y coordinate to y. Zooming is by powers of two and 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 top to bottom.

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

Fbseek 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 fbseek after every read or write since both fbrpixel and fbwpixel 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.

Fbtell 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.

Fbrpixel reads the pixel at the current frame buffer location and returns it into the location specifed by pp. A return of -1 indicates an error while trying to access the frame buffer.

Fbwpixel writes the pixel pointed to by pp at the current frame buffer location. A return of -1 indicates an error while trying to access the frame buffer.

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

EXAMPLE
Libfb can be loaded with any C program:

    $ cc -I/vld/include program.c /vld/lib/libfb.a

FILES
/vld/include/fb.h
/vld/lib/libfb.a

SEE ALSO
ik(4B), fb(5B), rle(5B).

RETURN VALUES
Fbopen, fbclose, fbwrite, fbread, fb_wmap, fb_rmap, fbclear, fbcursor, fbscursor, fbsetcursor, fbwindow, fbzoom, fbseek, fbwpixel, fbrpixel and fbflush return -1 to indicate failure, and except for fbopen they all return 0 to indicate success.

AUTHORS
Douglas P. Kingston III, BRL/VLD-VMB
Mike J. Muuss, BRL/SECAD-CSMB
Gary S. Moss, BRL/VLD-VMB

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

The package will only handle one open frame buffer at a time.