Revision: 49894
http://brlcad.svn.sourceforge.net/brlcad/?rev=49894&view=rev
Author: starseeker
Date: 2012-04-03 17:31:26 +0000 (Tue, 03 Apr 2012)
Log Message:
-----------
Uh, what? didn't mean to change libfb.3
Modified Paths:
--------------
brlcad/trunk/src/libfb/libfb.3
Modified: brlcad/trunk/src/libfb/libfb.3
===================================================================
--- brlcad/trunk/src/libfb/libfb.3 2012-04-03 17:26:42 UTC (rev 49893)
+++ brlcad/trunk/src/libfb/libfb.3 2012-04-03 17:31:26 UTC (rev 49894)
@@ -1,383 +1,487 @@
-'\" t
-.\" Title: libfb - FrameBuffer Library
-.\" Author: BRL-CAD Team
-.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\" Date: 04/03/2012
-.\" Manual: BRL-CAD Libraries
-.\" Source: BRL-CAD
-.\" Language: English
+.TH LIBFB 3 BRL-CAD
+.\" L I B F B . 3
+.\" BRL-CAD
.\"
-.TH "LIBFB \- FRAMEBUFFER" "3" "04/03/2012" "BRL\-CAD" "BRL\-CAD Libraries"
-.\" -----------------------------------------------------------------
-.\" * Define some portability stuff
-.\" -----------------------------------------------------------------
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" http://bugs.debian.org/507673
-.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.ie \n(.g .ds Aq \(aq
-.el .ds Aq '
-.\" -----------------------------------------------------------------
-.\" * set default formatting
-.\" -----------------------------------------------------------------
-.\" disable hyphenation
-.nh
-.\" disable justification (adjust text to left margin only)
-.ad l
-.\" -----------------------------------------------------------------
-.\" * MAIN CONTENT STARTS HERE *
-.\" -----------------------------------------------------------------
-.SH "NAME"
+.\" Copyright (c) 2005-2012 United States Government as represented by
+.\" the U.S. Army Research Laboratory.
+.\"
+.\" Redistribution and use in source (Docbook format) and 'compiled'
+.\" forms (PDF, PostScript, HTML, RTF, etc), with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code (Docbook format) must retain the
+.\" above copyright notice, this list of conditions and the following
+.\" disclaimer.
+.\"
+.\" 2. Redistributions in compiled form (transformed to other DTDs,
+.\" converted to PDF, PostScript, HTML, RTF, and other formats) must
+.\" reproduce the above copyright notice, this list of conditions and
+.\" the following disclaimer in the documentation and/or other
+.\" materials provided with the distribution.
+.\"
+.\" 3. The name of the author may not be used to endorse or promote
+.\" products derived from this documentation without specific prior
+.\" written permission.
+.\"
+.\" THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR AS IS'' AND ANY
+.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+.\" OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
+.\" USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\".\".\"
+.SH NAME
libfb \- multiple device, generic frame buffer library
-.SH "GENERIC FRAME BUFFER ROUTINES"
-.HP \w'FBIO\ *fb_open('u
-.BI "FBIO *fb_open(*\ " "fbfile" ", int\ fb_close\ (\ fbp\ )\ FBIO\ *\ " "fbp"
", int\ fb_read\ (\ fbp\ ,\ x\ ,\ y\ ,\ addr\ ,\ count\ )\ FBIO\ *\ " "fbp" ");"
-.sp
-.if n \{\
-.RS 4
-.\}
-.ft B
+.SH SYNOPSIS
.nf
- RGBpixel *addr;
- long count;
-
-
-.fi
-.ft
-.if n \{\
-.RE
-.\}
-.HP \w'int\ fb_write('u
-.BI "int fb_write(*\ " "fbp" ", RGBpixel\ *\ " "addr" ", long\ " "count" ",
int\ fb_rmap\ (\ fbp\ ,\ cmap\ )\ FBIO\ *\ " "fbp" ", ColorMap\ *\ " "cmap" ");"
-.HP \w'int\ fb_wmap('u
-.BI "int fb_wmap(*\ " "fbp" ", ColorMap\ *\ " "cmap" ");"
-.HP \w'int\ fb_clear('u
-.BI "int fb_clear(*\ " "fbp" ", RGBpixel\ *\ " "colorp" ");"
-.HP \w'char\ *fb_gettype('u
-.BI "char *fb_gettype(*\ " "fbp" ");"
-.HP \w'int\ fb_getwidth('u
-.BI "int fb_getwidth(*\ " "fbp" ");"
-.HP \w'int\ fb_getheight('u
-.BI "int fb_getheight(*\ " "fbp" ");"
-.SH "HARDWARE SPECIFIC FRAME BUFFER ROUTINES"
-.HP \w'int\ fb_cursor('u
-.BI "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" "[]);"
-.sp
-.if n \{\
-.RS 4
-.\}
-.ft B
-.nf
- int xbits, ybits;
- int xorig, yorig;
-
-
-.fi
-.ft
-.if n \{\
-.RE
-.\}
-.HP \w'int\ fb_window('u
-.BI "int fb_window(*\ " "fbp" ", int\ fb_zoom\ (\ fbp\ ,\ x\ ,\ y\ )\ FBIO\ *\
" "fbp" ", /\ *Buffered\ frame\ buffer\ I/O:\ */\ int\ fb_ioinit\ (\ fbp\ )\
FBIO\ *\ " "fbp" ");"
-.HP \w'int\ fb_seek('u
-.BI "int fb_seek(*\ " "fbp" ", void\ fb_tell\ (\ fbp\ ,\ xp\ ,\ yp\ )\ FBIO\
*\ " "fbp" ", int\ *xp\ ,\ *\ " "yp" ");"
-.HP \w'int\ fb_rpixel('u
-.BI "int fb_rpixel(*\ " "fbp" ", RGBpixel\ *\ " "pixelp" ");"
-.HP \w'int\ fb_wpixel('u
-.BI "int fb_wpixel(*\ " "fbp" ", RGBpixel\ *\ " "pixelp" ");"
-.HP \w'int\ fb_flush('u
-.BI "int fb_flush(*\ " "fbp" ");"
-.HP \w'void\ fb_log('u
-.BI "void fb_log(format\ [\ " "" ", arg\ ]\ \&.\&.\&.\ " "" ");"
-.SH "DESCRIPTION"
+.B #include <fb.h>
.PP
-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\&.
+/* Generic frame buffer routines: */
.PP
-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
-\fBRGBpixel\fRs, which is a typedef for an array of three unsigned chars (this
was done to avoid structure padding)\&. Note that a pointer to an
-\fBRGBpixel\fR
+.B FBIO "*fb_open(fbfile, width, height)"
+.B char *fbfile;
+.PP
+.B int fb_close(fbp)
+.B FBIO *fbp;
+.PP
+.B int "fb_read(fbp, x, y, addr, count)"
+.B FBIO *fbp;
+.B RGBpixel *addr;
+.B size_t count;
+.PP
+.B int "fb_write(fbp, x, y, addr, count)"
+.B FBIO *fbp;
+.B RGBpixel *addr;
+.B size_t count;
+.PP
+.B int fb_rmap(fbp, cmap)
+.B FBIO *fbp;
+.B ColorMap *cmap;
+.PP
+.B int fb_wmap(fbp, cmap)
+.B FBIO *fbp;
+.B ColorMap *cmap;
+.PP
+.B int fb_clear(fbp, colorp)
+.B FBIO *fbp;
+.B RGBpixel *colorp;
+.PP
+.B char *fb_gettype(fbp)
+.B FBIO *fbp;
+.PP
+.B int fb_getwidth(fbp)
+.B FBIO *fbp;
+.PP
+.B int fb_getheight(fbp)
+.B FBIO *fbp;
+.PP
+/* Hardware specific frame buffer routines: */
+.PP
+.B int fb_cursor(fbp, mode, x, y)
+.B FBIO *fbp;
+.PP
+.B int fb_scursor(fbp, mode, x, y)
+.B FBIO *fbp;
+.PP
+.B int "fb_setcursor(fbp, bits, xbits, ybits, xorig, yorig)"
+.B FBIO *fbp;
+.B unsigned char bits[];
+.B int xbits, ybits;
+.B int xorig, yorig;
+.PP
+.B int fb_window(fbp, x, y)
+.B FBIO *fbp;
+.PP
+.B int fb_zoom(fbp, x, y)
+.B FBIO *fbp;
+.PP
+/* Buffered frame buffer I/O: */
+.PP
+.B int fb_ioinit(fbp)
+.B FBIO *fbp;
+.PP
+.B int fb_seek(fbp, x, y)
+.B FBIO *fbp;
+.PP
+.B void fb_tell(fbp, xp, yp)
+.B FBIO *fbp;
+.B int *xp, *yp;
+.PP
+.B int fb_rpixel(fbp, pixelp)
+.B FBIO *fbp;
+.B RGBpixel *pixelp;
+.PP
+.B int fb_wpixel(fbp, pixelp)
+.B FBIO *fbp;
+.B RGBpixel *pixelp;
+.PP
+.B int fb_flush(fbp)
+.B FBIO *fbp;
+.PP
+.B void "fb_log(format [, arg ] ... )"
+.B char *format;
+.SH 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.
+.PP
+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
+.BR RGBpixel s,
+which is a typedef for an array of three unsigned chars (this was
+done to avoid structure padding). Note that a pointer to an
+.B RGBpixel
is thus the name of the
-\fBRGBpixel\fR
-itself, i\&.e\&. no ampersand is needed\&.
+.B RGBpixel
+itself, i.e. no ampersand is needed.
.PP
-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\&.
+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.
.PP
-
-\fIFb_open\fR
+.I Fb_open\^
is used to open a frame buffer file
-\fIfbfile\fR\&. 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
-\fIfbfile\fR
+.IR 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
+.I fbfile\^
is
-
-NULL
+.B
+.SM NULL
and the environment variable
-
-\fBFB_FILE\fR
+.B
+.SM FB_FILE
is set, then the value of
-\fBFB_FILE\fR
-is used; otherwise the default frame buffer device for the system is used\&.
See below for more details\&. The
-\fIwidth\fR
+.SM FB_FILE
+is used;
+otherwise the default frame buffer device for the system is used.
+See below for more details.
+The
+.I width\^
and
-\fIheight\fR
-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\&.
+.I 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.
.PP
-
-\fIFb_close\fR
-simply closes the frame buffer\&.
+.I Fb_close\^
+simply closes the frame buffer.
.PP
-
-\fIFb_read\fR
+.I Fb_read\^
reads
-\fIcount\fR
+.I count\^
pixels from the frame buffer starting at the location specified by
-\fIx\fR
+.I x\^
and
-\fIy\fR, and places them at program memory address specified by
-\fIaddr\fR\&.
-\fIFb_read\fR
-returns the number of pixels actually read, or \-1 on error\&.
+.IR y\^ ,
+and places them at program memory address specified
+by
+.IR addr\^ .
+.I Fb_read\^
+returns the number of pixels actually read, or -1 on error.
.PP
-
-\fIFb_write\fR
+.I Fb_write\^
writes
-\fIcount\fR
+.I count\^
pixels from program address
-\fIaddr\fR
-into the frame buffer starting at the location specified by
-\fIx\fR
+.I addr\^
+into the frame buffer starting at the location
+specified
+by
+.I x\^
and
-\fIy\fR\&.
-\fIFb_write\fR
-returns the number of pixels actually written, or \-1 on error\&.
+.IR y\^ .
+.I Fb_write\^
+returns the number of pixels actually written, or
+-1 on error.
.PP
-
-\fIFb_rmap\fR
-reads in the color map from the frame buffer and leaves at the location
pointed to by
-\fIcmap\fR\&.
+.I Fb_rmap\^
+reads in the color map from the frame buffer and
+leaves at the location pointed to by
+.IR cmap\^ .
.PP
-
-\fIFb_wmap\fR
+.I Fb_wmap\^
writes the color map pointed to by
-\fIcmap\fR
-into the frame buffer\&. If the value of
-\fIcmap\fR
+.I cmap\^
+into the frame buffer. If the value of
+.I cmap\^
is
-
-NULL
-then a linear color map is used as the default\&.
+.B
+.SM NULL
+then a linear color map is used as the default.
.PP
-
-\fIFb_clear\fR
-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\&.
+.I 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.
.PP
-
-\fIFb_gettype\fR
-returns a pointer to a string describing the frame buffer specified by the
FBIO pointer\&.
+.I Fb_gettype\^
+returns a pointer to a string describing the frame buffer
+specified by the FBIO pointer.
.PP
-
-\fIFb_getwidth\fR
+.I Fb_getwidth\^
and
-\fIFb_getheight\fR
-returns the current size of the FBIO frame buffer\&.
+.I Fb_getheight\^
+returns the current size of the FBIO frame buffer.
.PP
-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\&.
+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.
.PP
-
-\fIFb_cursor\fR
+.I Fb_cursor\^
places the cursor at the image space coordinates given by
-\fIx\fR
+.I x\^
and
-\fIy\fR\&. If the mode is non\-zero, the cursor is made visible, and if mode
is zero, the cursor is turned off\&.
+.IR y\^ .
+If the mode is non-zero, the cursor is made visible, and
+if mode is zero, the cursor is turned off.
.PP
-
-\fIFb_scursor\fR
+.I Fb_scursor\^
is the same as
-\fIfb_cursor\fR
-except that it places the cursor at the
-\fBscreen\fR
+.I fb_cursor\^
+except that it
+places the cursor at the
+.B screen
space coordinates given by
-\fIx\fR
+.I x\^
and
-\fIy\fR\&.
+.IR y\^ .
.PP
-
-\fIFb_setcursor\fR
-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
-\fIbits\fR
-is a pointer to an array of unsigned chars containing the bits of the
cursor\&. The arguments
-\fIxbits\fR
+.I 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
+.I bits\^
+is a pointer to an array
+of unsigned chars containing the bits of the cursor.
+The arguments
+.I xbits
and
-\fIybits\fR
-specify the size of the cursor bitmap\&. The number of bytes in the
-\fIbits\fR
-array will be the width rounded up to a mutiple of eight (so that the cursor
"scanlines" are byte aligned) times the height\&.
-\fIbits\fR[0] is the lower left corner,
-\fIbits\fR[1] is to the right of it, etc\&. The next line of the
-\fIbits\fR
-array goes above the current one\&. Within a byte the most significant bit is
the leftmost\&. The values
-\fIxorig\fR
+.I ybits
+specify the size of the cursor bitmap. The number of bytes in the
+.I bits
+array will be the width rounded up to a mutiple of
+eight (so that the cursor "scanlines" are byte aligned) times the
+height.
+.IR bits [0]
+is the lower left corner,
+.IR bits [1]
+is to the right of it, etc. The next line of the
+.I bits
+array goes above the current one. Within a byte the most significant
+bit is the leftmost. The values
+.I xorig
and
-\fIyorig\fR
-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\&.
+.I 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.
.PP
-
-\fIFb_window\fR
-sets the frame buffer window center position to the image space coordinates
given by
-\fIx\fR
+.I Fb_window\^
+sets the frame buffer window center position to the image space coordinates
+given by
+.I x\^
and
-\fIy\fR\&. This command is usually used in conjunction with the
-\fIfb_zoom\fR
-routine\&.
+.IR y\^ .
+This command is usually used in conjunction with the
+.I fb_zoom\^
+routine.
.PP
-
-\fIFb_zoom\fR
-sets the zoom factor for the X coordinate to
-\fIx\fR
-and the zoom factor for the Y coordinate to
-\fIy\fR\&. Zooming is generally done by pixel replication in hardware\&.
+.I Fb_zoom\^
+sets the zoom factor for the X coordinate
+to
+.I x\^
+and the zoom factor for the Y coordinate
+to
+.IR y\^ .
+Zooming is generally done
+by pixel replication in hardware.
.PP
-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 \(lqbands\(rq of the image in core\&. Since horizontal bands are buffered,
the ideal motion is to scan left to right, then bottom to top\&.
+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.
.PP
-
-\fIFb_ioinit\fR
-should be called before using any of the other buffered I/O routines and
repeated whenever the frame buffer is reopened\&.
+.I Fb_ioinit\^
+should be called before using any of the other buffered I/O routines and
+repeated whenever the frame buffer is reopened.
.PP
-
-\fIFb_seek\fR
-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
-\fIfb_seek\fR
+.I 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
+.I fb_seek\^
after every read or write since both
-\fIfb_rpixel\fR
+.I fb_rpixel\^
and
-\fIfb_wpixel\fR
-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\&.
+.I 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.
.PP
-
-\fIFb_tell\fR
-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
-\fIxp\fR
+.I 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
+.I xp\^
and
-\fIyp\fR\&.
+.IR yp\^ .
.PP
-
-\fIFb_rpixel\fR
-reads the pixel at the current frame buffer location and returns it into the
location specifed by
-\fIpixelp\fR\&.
+.I Fb_rpixel\^
+reads the pixel at the current frame buffer location
+and returns it into the location specifed
+by
+.IR pixelp\^ .
.PP
-
-\fIFb_wpixel\fR
+.I Fb_wpixel\^
writes the pixel pointed to by
-\fIpixelp\fR
-at the current frame buffer location\&.
+.I pixelp\^
+at the current frame buffer location.
.PP
-
-\fIFb_flush\fR
-caused any current buffered frame buffer pages to be written out\&.
Unnecessary writes are avoided by the use of page reference bits\&.
+.I Fb_flush\^
+caused any current buffered frame buffer pages to be written out.
+Unnecessary writes are avoided by the use of page reference bits.
.PP
-The following is a printing routine which this library uses to indicate
errors\&.
+The following is a printing routine which this library uses to
+indicate errors.
.PP
-
-\fIFb_log\fR
+.I Fb_log\^
will convert, format and print its
-\fIargs\fR
+.I args\^
under control of
-\fIformat\fR
-to the standard error output\&. For more detailed information on the
specification of the control string, see
-\fBprintf\fR(3S)\&. This function may be supplied by the application if
different behavior is desired\&.
+.I format\^
+to the standard error output.
+For more detailed information on the specification of the control string,
+see
+.IR printf\^ (3S).
+This function may be supplied by the application if different behavior
+is desired.
.SH "FB_FILE DEVICES"
-.PP
-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\&.
-.PP
-/dev/debug\fI[num]\fR
-.RS 4
-The "/dev/debug" interface prints one line to logs each call to the frame
buffer library\&.
-
-\fInum\fR
-is a bitvector indicating the levels of verbosity of the output\&. See
-\fBfb\&.h\fR
-for the bit definitions\&.
-.RE
-.PP
-\fIfilename\fR
-.RS 4
+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.
+.TP
+.BI /dev/debug [num]
+The "/dev/debug" interface prints one line to logs each call
+to the frame buffer library.
+.br
+.I num
+is a bitvector indicating the levels of verbosity of the output. See
+.B fb.h
+for the bit definitions.
+.TP
+.I filename
Disk file interface
-.RE
+.TP
+.BI hostname: [devicename]
+TCP-based network links to a remote framebuffer, where
+.I devicename
+is any from this list, for example,
+fictitious.brlcad.org:/dev/ik0 or fictitious.brlcad.org:/dev/sgi.
+A
+.B hostname
+with a null
+.I 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.
+.SH EXAMPLE
+.I Libfb\^
+can be loaded with any
+C
+program:
.PP
-\fBhostname:\fR\fI[devicename]\fR
-.RS 4
-TCP\-based network links to a remote framebuffer, where
-\fIdevicename\fR
-is any from this list, for example, fictitious\&.brlcad\&.org:/dev/ik0 or
fictitious\&.brlcad\&.org:/dev/sgi\&. A
-\fBhostname\fR
-with a null\fIdevicename\fR
-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\&.
+.RS
+$ \|\fI/bin/cc \|program.c \|-lfb -l\<system-library...\>\fP
.RE
-.SH "EXAMPLES"
-.PP
-
-\fILibfb\fR
-can be loaded with any C program:
.sp
-.if n \{\
-.RS 4
-.\}
-.nf
+where
+.I <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.
.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-$ /bin/cc program\&.c \-lfb \-l\e<system\-library\&.\&.\&.\e>
-.fi
-.if n \{\
-.RE
-.\}
-.sp
-
-
-.fi
-.if n \{\
-.RE
-.\}
-.PP
-where
-\fI<system\-library>\fR
-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\&.
+.SH FILES
+fb.h
+.br
+/usr/brl/lib/libfb.a
+.SH "SEE ALSO"
+fbhelp(1), brlcad(1).
.SH "RETURN VALUES"
-.PP
-
-\fIfb_close\fR,
-\fIfb_write\fR,
-\fIfb_read\fR,
-\fIfb_wmap\fR,
-\fIfb_rmap\fR,
-\fIfb_clear\fR,
-\fIfb_cursor\fR,
-\fIfb_scursor\fR,
-\fIfb_setcursor\fR,
-\fIfb_window\fR,
-\fIfb_zoom\fR,
-\fIfb_ioinit\fR,
-\fIfb_seek\fR,
-\fIfb_wpixel\fR,
-\fIfb_rpixel\fR
+.IR fb_close\^ ,
+.IR fb_write\^ ,
+.IR fb_read\^ ,
+.IR fb_wmap\^ ,
+.IR fb_rmap\^ ,
+.IR fb_clear\^ ,
+.IR fb_cursor\^ ,
+.IR fb_scursor\^ ,
+.IR fb_setcursor\^ ,
+.IR fb_window\^ ,
+.IR fb_zoom\^ ,
+.IR fb_ioinit\^ ,
+.IR fb_seek\^ ,
+.IR fb_wpixel\^ ,
+.I fb_rpixel\^
and
-\fIfb_flush\fR
-return \-1 to indicate failure\&.
-\fIFb_open\fR
-returns FBIO_NULL to indicate failure, and a non\-null FBIO structure pointer
upon success\&.
-\fIfb_read\fR, and
-\fIfb_write\fR
-return the number of pixels actually read or written\&.
-\fIfb_gettype\fR
-returns a pointer to a NULL terminated description string\&.
-.SH "SEE ALSO"
-.PP
-\fBfbhelp\fR(1),
-\fBbrlcad\fR(1)\&.
+.I fb_flush\^
+return \-1 to indicate failure.
+.I Fb_open\^
+returns FBIO_NULL to indicate failure, and a non-null FBIO structure pointer
+upon success.
+.IR fb_read\^ ,
+and
+.IR fb_write\^
+return the number of pixels actually read or written.
+.IR fb_gettype\^
+returns a pointer to a NULL terminated description string.
+.SH BUGS
+Vertical scanning will incur the most overhead, making it almost
+impractical.
+Due to the way memory is organized
+in frame buffers and UNIX files, vertical scanning will never
+be easy unless the image can be rotated.
.SH "BUG REPORTS"
-.PP
-Reports of bugs or problems should be submitted via electronic mail to
<devs@brlcad\&.org>, or via the "cadbug\&.sh" script\&.
-.SH "AUTHOR"
-.PP
-\fBBRL\-CAD Team\fR
+Reports of bugs or problems should be submitted via electronic
+mail to <d...@brlcad.org>.
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
Better than sec? Nothing is better than sec when it comes to
monitoring Big Data applications. Try Boundary one-second
resolution app monitoring today. Free.
http://p.sf.net/sfu/Boundary-dev2dev
_______________________________________________
BRL-CAD Source Commits mailing list
brlcad-commits@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/brlcad-commits
