Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LIBFB -	FRAMEBUFFER(3)	       BRL-CAD Libraries	LIBFB -	FRAMEBUFFER(3)

NAME
       libfb - multiple	device,	generic	frame buffer library

GENERIC	FRAME BUFFER ROUTINES
       FBIO *fb_open(* 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, RGBpixel * addr, long count,
		    int	fb_rmap	( fbp ,	cmap ) FBIO * fbp, ColorMap * cmap);

       int fb_wmap(* fbp, ColorMap * cmap);

       int fb_clear(* fbp, RGBpixel * colorp);

       char *fb_gettype(* fbp);

       int fb_getwidth(* fbp);

       int fb_getheight(* fbp);

HARDWARE SPECIFIC FRAME	BUFFER ROUTINES
       int fb_cursor(* 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, int	fb_zoom	( fbp ,	x , y )	FBIO * fbp,
		     / *Buffered frame buffer I/O: */ int fb_ioinit ( fbp ) FBIO * fbp);

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

       int fb_rpixel(* fbp, RGBpixel * pixelp);

       int fb_wpixel(* fbp, RGBpixel * pixelp);

       int fb_flush(* fbp);

       void fb_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 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	(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 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	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 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 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).

AUTHOR
       BRL-CAD Team

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

BRL-CAD				  07/08/2017		LIBFB -	FRAMEBUFFER(3)

NAME | GENERIC FRAME BUFFER ROUTINES | HARDWARE SPECIFIC FRAME BUFFER ROUTINES | DESCRIPTION | FB_FILE DEVICES | EXAMPLES | RETURN VALUES | SEE ALSO | AUTHOR | BUG REPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=libfb&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help