## Name

libfb — multiple device, generic frame buffer library

## Generic frame buffer routines

`fsfuncFBIO *fb_open(` | fbfile, |
| fbp, |
| fbp`)`; |

`* fbfile`;
`int fb_close ( fbp ) FBIO * fbp`;
`int fb_read ( fbp , x , y , addr , count ) FBIO * fbp`;

        RGBpixel *addr;
        long count;

`int fsfuncfb_write(` | fbp, |
| addr, |
| count, |
| fbp, |
| cmap`)`; |

`* fbp`;
`RGBpixel * addr`;
`long count`;
`int fb_rmap ( fbp , cmap ) FBIO * fbp`;
`ColorMap * cmap`;

`int fsfuncfb_wmap(` | fbp, |
| cmap`)`; |

`* fbp`;
`ColorMap * cmap`;

`int fsfuncfb_clear(` | fbp, |
| colorp`)`; |

`* fbp`;
`RGBpixel * colorp`;

`char *fsfuncfb_gettype(` | fbp`)`; |

`* fbp`;

`int fsfuncfb_getwidth(` | fbp`)`; |

`* fbp`;

`int fsfuncfb_getheight(` | fbp`)`; |

`* fbp`;

## Hardware specific frame buffer routines

`int fsfuncfb_cursor(` | fbp, |
| fbp, |
| fbp, |
| bits`)`; |

`* 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 fsfuncfb_window(` | fbp, |
| fbp, |
| fbp`)`; |

`* fbp`;
`int fb_zoom ( fbp , x , y ) FBIO * fbp`;
`/ *Buffered frame buffer I/O: */ int fb_ioinit ( fbp ) FBIO * fbp`;

`int fsfuncfb_seek(` | fbp, |
| fbp, |
| yp`)`; |

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

`int fsfuncfb_rpixel(` | fbp, |
| pixelp`)`; |

`* fbp`;
`RGBpixel * pixelp`;

`int fsfuncfb_wpixel(` | fbp, |
| pixelp`)`; |

`* fbp`;
`RGBpixel * pixelp`;

`int fsfuncfb_flush(` | fbp`)`; |

`* fbp`;

`void fsfuncfb_log(` | , |
| `)`; |

`format [` ;
`arg ] ...` ;

## 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

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

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

## SEE ALSO

fbhelp(1), brlcad(1).

## BUG REPORTS

Reports of bugs or problems should be submitted via electronic mail to <devs@brlcad.org>, or via the "cadbug.sh" script.