Generic frame buffer routines

Hardware specific frame buffer routines

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.

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.

SEE ALSO

fbhelp(1), brlcad(1).

AUTHOR

BRL-CAD Team

BUG REPORTS

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