libfb - FrameBuffer Library(3)

NAME

libfb - multiple device, generic frame buffer library

Generic frame buffer routines

fb *fb_open (* fbfile,
             int fb_close ( fbp ) fb * fbp,
             int fb_read ( fbp , x , y , addr , count ) fb * fbp,
             RGBpixel *addr;,
             long count;);

Hardware specific frame buffer routines

int fb_cursor (* fbp,
               int fb_scursor ( fbp , mode , x , y ) fb * fbp,
               int fb_setcursor ( fbp , bits , xbits , ybits , xorig , yorig ) fb * fbp,
               unsigned char bits[],
               int xbits, ybits;,
               int xorig, yorig;);

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 accommodate 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 (fb) 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 FB_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 fb pointer.
Fb_getwidth and Fb_getheight: returns the current size of the fb 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 multiple 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 specified 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
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.

EXAMPLES

Libfb can be loaded with any C program:

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

where <system-library> denotes specific libraries necessary 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.

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 FB_NULL to indicate failure, and a non-null fb 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.

AUTHOR

BRL-CAD Team

COPYRIGHT

BUG REPORTS

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