Revision: 53852
http://brlcad.svn.sourceforge.net/brlcad/?rev=53852&view=rev
Author: starseeker
Date: 2012-11-28 15:51:42 +0000 (Wed, 28 Nov 2012)
Log Message:
-----------
Commit man3 Docbook patch from GCI task
http://www.google-melange.com/gci/task/view/google/gci2012/7950213 by Cezar.
Modified Paths:
--------------
brlcad/trunk/doc/docbook/system/man3/en/libfb.xml
Modified: brlcad/trunk/doc/docbook/system/man3/en/libfb.xml
===================================================================
--- brlcad/trunk/doc/docbook/system/man3/en/libfb.xml 2012-11-28 15:46:51 UTC
(rev 53851)
+++ brlcad/trunk/doc/docbook/system/man3/en/libfb.xml 2012-11-28 15:51:42 UTC
(rev 53852)
@@ -1,496 +1,470 @@
+<?xml version="1.0"?>
<!-- Converted by db4-upgrade version 1.0 -->
-
<refentry xmlns="http://docbook.org/ns/docbook"; version="5.0" xml:id="libfb">
-
-<refmeta>
- <refentrytitle>libfb - FrameBuffer Library</refentrytitle>
- <manvolnum>3</manvolnum>
- <refmiscinfo class="source">BRL-CAD</refmiscinfo>
- <refmiscinfo class="manual">BRL-CAD Libraries</refmiscinfo>
-</refmeta>
-
-<refnamediv xml:id="name">
- <refname>libfb</refname>
- <refpurpose>
- multiple device, generic frame buffer library
- </refpurpose>
-</refnamediv>
-
-<!-- body begins here -->
-
-<refsection xml:id="libfbgeneric"><info><title>Generic frame buffer
routines</title></info>
-
- <funcprototype>
- <funcdef><function>FBIO</function> *fb_open</funcdef>
- <paramdef>* <parameter>fbfile</parameter></paramdef>
- <paramdef>int fb_close ( fbp ) FBIO * <parameter>fbp</parameter></paramdef>
- <paramdef>int fb_read ( fbp , x , y , addr , count ) FBIO *
<parameter>fbp</parameter></paramdef>
- </funcprototype>
- <funcsynopsisinfo>
- RGBpixel *addr;
- long count;
-
- </funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>fb_write</function></funcdef>
- <paramdef>* <parameter>fbp</parameter></paramdef>
- <paramdef>RGBpixel * <parameter>addr</parameter></paramdef>
- <paramdef>long <parameter>count</parameter></paramdef>
- <paramdef>int fb_rmap ( fbp , cmap ) FBIO *
<parameter>fbp</parameter></paramdef>
- <paramdef>ColorMap * <parameter>cmap</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>int <function>fb_wmap</function></funcdef>
- <paramdef>* <parameter>fbp</parameter></paramdef>
- <paramdef>ColorMap * <parameter>cmap</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>int <function>fb_clear</function></funcdef>
- <paramdef>* <parameter>fbp</parameter></paramdef>
- <paramdef>RGBpixel * <parameter>colorp</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>char *<function>fb_gettype</function></funcdef>
- <paramdef>* <parameter>fbp</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>int <function>fb_getwidth</function></funcdef>
- <paramdef>* <parameter>fbp</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>int <function>fb_getheight</function></funcdef>
- <paramdef>* <parameter>fbp</parameter></paramdef>
- </funcprototype>
-</refsection>
-
-<refsection xml:id="libfbhardware"><info><title>Hardware specific frame buffer
routines</title></info>
-
- <funcprototype>
- <funcdef>int <function>fb_cursor</function></funcdef>
- <paramdef>* <parameter>fbp</parameter></paramdef>
- <paramdef>int fb_scursor ( fbp , mode , x , y ) FBIO *
<parameter>fbp</parameter></paramdef>
- <paramdef>int fb_setcursor ( fbp , bits , xbits , ybits , xorig , yorig )
FBIO * <parameter>fbp</parameter></paramdef>
- <paramdef>unsigned char <parameter>bits</parameter>[]</paramdef>
- </funcprototype>
- <funcsynopsisinfo>
- int xbits, ybits;
- int xorig, yorig;
-
- </funcsynopsisinfo>
- <funcprototype>
- <funcdef>int <function>fb_window</function></funcdef>
- <paramdef>* <parameter>fbp</parameter></paramdef>
- <paramdef>int fb_zoom ( fbp , x , y ) FBIO *
<parameter>fbp</parameter></paramdef>
- <paramdef>/ *Buffered frame buffer I/O: */ int fb_ioinit ( fbp ) FBIO *
<parameter>fbp</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>int <function>fb_seek</function></funcdef>
- <paramdef>* <parameter>fbp</parameter></paramdef>
- <paramdef>void fb_tell ( fbp , xp , yp ) FBIO *
<parameter>fbp</parameter></paramdef>
- <paramdef>int *xp , * <parameter>yp</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>int <function>fb_rpixel</function></funcdef>
- <paramdef>* <parameter>fbp</parameter></paramdef>
- <paramdef>RGBpixel * <parameter>pixelp</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>int <function>fb_wpixel</function></funcdef>
- <paramdef>* <parameter>fbp</parameter></paramdef>
- <paramdef>RGBpixel * <parameter>pixelp</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>int <function>fb_flush</function></funcdef>
- <paramdef>* <parameter>fbp</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>void <function>fb_log</function></funcdef>
- <paramdef>format [ <parameter/></paramdef>
- <paramdef>arg ] ... <parameter/></paramdef>
- </funcprototype>
-</refsection>
-
-<refsection xml:id="description"><info><title>DESCRIPTION</title></info>
-
- <para>
- 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.
- </para>
-
- <para>
- 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 <emphasis
remap="B">RGBpixel</emphasis>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
- <emphasis remap="B">RGBpixel</emphasis>
- is thus the name of the <emphasis remap="B">RGBpixel</emphasis>
- itself, i.e. no ampersand is needed.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- <emphasis remap="I">Fb_open</emphasis> is used to open a frame buffer
- file <emphasis remap="I">fbfile</emphasis>. 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 <emphasis remap="I">fbfile</emphasis> is
- <!-- B elided -->
- <acronym>NULL</acronym> and the environment variable
- <!-- B elided -->
- <envar>FB_FILE</envar> is set, then the value of <envar>FB_FILE</envar>
- is used; otherwise the default frame buffer device for the system is used.
- See below for more details. The <emphasis remap="I">width</emphasis>
- and <emphasis remap="I">height</emphasis> 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.
- </para>
-
- <para>
- <emphasis remap="I">Fb_close</emphasis> simply closes the frame buffer.
- </para>
-
- <para>
- <emphasis remap="I">Fb_read</emphasis> reads
- <emphasis remap="I">count</emphasis> pixels from the frame buffer
- starting at the location specified by <emphasis remap="I">x</emphasis>
- and <emphasis remap="I">y</emphasis>, and places them at program
- memory address specified by <emphasis remap="I">addr</emphasis>.
- <emphasis remap="I">Fb_read</emphasis> returns the number of
- pixels actually read, or -1 on error.
- </para>
-
- <para>
- <emphasis remap="I">Fb_write</emphasis> writes
- <emphasis remap="I">count</emphasis> pixels from program address
- <emphasis remap="I">addr</emphasis> into the frame buffer starting
- at the location specified by <emphasis remap="I">x</emphasis>
- and <emphasis remap="I">y</emphasis>. <emphasis
remap="I">Fb_write</emphasis>
- returns the number of pixels actually written, or -1 on error.
- </para>
-
- <para>
- <emphasis remap="I">Fb_rmap</emphasis>
- reads in the color map from the frame buffer and
- leaves at the location pointed to by
- <emphasis remap="I">cmap</emphasis>.
- </para>
-
- <para>
- <emphasis remap="I">Fb_wmap</emphasis>
- writes the color map pointed to by
- <emphasis remap="I">cmap</emphasis>
- into the frame buffer. If the value of
- <emphasis remap="I">cmap</emphasis>
- is
- <!-- B elided -->
- <acronym>NULL</acronym>
- then a linear color map is used as the default.
- </para>
-
- <para>
- <emphasis remap="I">Fb_clear</emphasis>
- 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.
- </para>
-
- <para>
- <emphasis remap="I">Fb_gettype</emphasis>
- returns a pointer to a string describing the frame buffer
- specified by the FBIO pointer.
- </para>
-
- <para>
- <emphasis remap="I">Fb_getwidth</emphasis>
- and <emphasis remap="I">Fb_getheight</emphasis>
- returns the current size of the FBIO frame buffer.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- <emphasis remap="I">Fb_cursor</emphasis>
- places the cursor at the image space coordinates given by
- <emphasis remap="I">x</emphasis>
- and
- <emphasis remap="I">y</emphasis>.
- If the mode is non-zero, the cursor is made visible, and
- if mode is zero, the cursor is turned off.
- </para>
-
- <para>
- <emphasis remap="I">Fb_scursor</emphasis>
- is the same as
- <emphasis remap="I">fb_cursor</emphasis>
- except that it
- places the cursor at the
- <emphasis remap="B">screen</emphasis>
- space coordinates given by
- <emphasis remap="I">x</emphasis>
- and
- <emphasis remap="I">y</emphasis>.
- </para>
-
- <para>
- <emphasis remap="I">Fb_setcursor</emphasis>
- 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 <emphasis remap="I">bits</emphasis>
- is a pointer to an array of unsigned chars containing the bits of the
cursor.
- The arguments <emphasis remap="I">xbits</emphasis>
- and <emphasis remap="I">ybits</emphasis>
- specify the size of the cursor bitmap. The number of bytes in the
- <varname role="parameter">bits</varname> array will be the width rounded
- up to a multiple of eight (so that the cursor "scanlines" are byte aligned)
- times the height.
- <varname role="parameter">bits</varname>[0]
- is the lower left corner,
- <varname role="parameter">bits</varname>[1]
- is to the right of it, etc. The next line of the
- <varname role="parameter">bits</varname>
- array goes above the current one. Within a byte the most significant
- bit is the leftmost. The values
- <emphasis remap="I">xorig</emphasis>
- and <emphasis remap="I">yorig</emphasis>
- 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.
- </para>
-
- <para>
- <emphasis remap="I">Fb_window</emphasis>
- sets the frame buffer window center position to the image space coordinates
- given by <emphasis remap="I">x</emphasis> and <emphasis
remap="I">y</emphasis>.
- This command is usually used in conjunction with the
- <emphasis remap="I">fb_zoom</emphasis> routine.
- </para>
-
- <para>
- <emphasis remap="I">Fb_zoom</emphasis>
- sets the zoom factor for the X coordinate to
- <emphasis remap="I">x</emphasis>
- and the zoom factor for the Y coordinate to
- <emphasis remap="I">y</emphasis>.
- Zooming is generally done by pixel replication in hardware.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- <emphasis remap="I">Fb_ioinit</emphasis>
- should be called before using any of the other buffered I/O routines and
- repeated whenever the frame buffer is reopened.
- </para>
-
- <para>
- <emphasis remap="I">Fb_seek</emphasis>
- 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 <emphasis remap="I">fb_seek</emphasis>
- after every read or write since both <emphasis
remap="I">fb_rpixel</emphasis>
- and <emphasis remap="I">fb_wpixel</emphasis> 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.
- </para>
-
- <para>
- <emphasis remap="I">Fb_tell</emphasis>
- 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 <emphasis remap="I">xp</emphasis> and <emphasis remap="I">yp</emphasis>.
- </para>
-
- <para>
- <emphasis remap="I">Fb_rpixel</emphasis>
- reads the pixel at the current frame buffer location
- and returns it into the location specified
- by <emphasis remap="I">pixelp</emphasis>.
- </para>
-
- <para>
- <emphasis remap="I">Fb_wpixel</emphasis>
- writes the pixel pointed to by <emphasis remap="I">pixelp</emphasis>
- at the current frame buffer location.
- </para>
-
- <para>
- <emphasis remap="I">Fb_flush</emphasis>
- caused any current buffered frame buffer pages to be written out.
- Unnecessary writes are avoided by the use of page reference bits.
- </para>
-
- <para>
- The following is a printing routine which this library uses to
- indicate errors.
- </para>
-
- <para>
- <emphasis remap="I">Fb_log</emphasis> will convert, format and print its
- <emphasis remap="I">args</emphasis> under control of
- <emphasis remap="I">format</emphasis> to the standard error output.
- For more detailed information on the specification of the control string,
- see <citerefentry><refentrytitle>printf</refentrytitle>
- <manvolnum>3S</manvolnum></citerefentry>.
- This function may be supplied by the application if different behavior
- is desired.
- </para>
-</refsection>
-
-<refsection xml:id="fb_file_devices"><info><title>FB_FILE
DEVICES</title></info>
-
- <para>
- 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.
- </para>
- <variablelist remap="TP">
- <varlistentry>
- <term><filename>/dev/debug</filename><emphasis
remap="I">[num]</emphasis></term>
- <listitem>
- <para>The "/dev/debug" interface prints one line to logs each call
- to the frame buffer library.
- <!-- .br -->
- <emphasis remap="I">num</emphasis>
- is a bitvector indicating the levels of verbosity of the output. See
- <emphasis remap="B">fb.h</emphasis>
- for the bit definitions.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis remap="I">filename</emphasis></term>
- <listitem>
- <para>Disk file interface</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis remap="B">hostname:</emphasis><emphasis
remap="I">[devicename]</emphasis></term>
- <listitem>
- <para>TCP-based network links to a remote framebuffer, where
- <emphasis remap="I">devicename</emphasis>
- is any from this list, for example,
- fictitious.brlcad.org:/dev/ik0 or fictitious.brlcad.org:/dev/sgi.
- A <emphasis remap="B">hostname</emphasis>
- with a null<emphasis remap="I">devicename</emphasis>
- 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.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-</refsection>
-
-<refsection xml:id="examples"><info><title>EXAMPLES</title></info>
-
- <para>
- <emphasis remap="I">Libfb</emphasis>
- can be loaded with any C program:
- </para>
-
- <literallayout remap="RS" class="normal">
-<synopsis format="linespecific">
-$ <filename>/bin/cc program.c -lfb -l\<system-library...\></filename>
-</synopsis>
- </literallayout> <!-- remap='RE' -->
-
- <para>
- where <emphasis remap="I"><system-library></emphasis>
- 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.
- </para>
-</refsection>
-
-<refsection xml:id="return_values"><info><title>RETURN VALUES</title></info>
-
- <para>
- <emphasis remap="I">fb_close</emphasis>,
- <emphasis remap="I">fb_write</emphasis>,
- <emphasis remap="I">fb_read</emphasis>,
- <emphasis remap="I">fb_wmap</emphasis>,
- <emphasis remap="I">fb_rmap</emphasis>,
- <emphasis remap="I">fb_clear</emphasis>,
- <emphasis remap="I">fb_cursor</emphasis>,
- <emphasis remap="I">fb_scursor</emphasis>,
- <emphasis remap="I">fb_setcursor</emphasis>,
- <emphasis remap="I">fb_window</emphasis>,
- <emphasis remap="I">fb_zoom</emphasis>,
- <emphasis remap="I">fb_ioinit</emphasis>,
- <emphasis remap="I">fb_seek</emphasis>,
- <emphasis remap="I">fb_wpixel</emphasis>,
- <emphasis remap="I">fb_rpixel</emphasis>
- and
- <emphasis remap="I">fb_flush</emphasis>
- return -1 to indicate failure.
- <emphasis remap="I">Fb_open</emphasis>
- returns FBIO_NULL to indicate failure, and a non-null FBIO structure
pointer
- upon success.
- <emphasis remap="I">fb_read</emphasis>,
- and
- <emphasis remap="I">fb_write</emphasis>
- return the number of pixels actually read or written.
- <emphasis remap="I">fb_gettype</emphasis>
- returns a pointer to a NULL terminated description string.
- </para>
-</refsection>
-
-<refsection xml:id="see_also"><info><title>SEE ALSO</title></info>
-<para><citerefentry><refentrytitle>fbhelp</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>brlcad</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
-</refsection>
-
-<info><corpauthor>BRL-CAD Team</corpauthor></info>
-
-<refsection xml:id="bug_reports"><info><title>BUG REPORTS</title></info>
-
- <para>
- Reports of bugs or problems should be submitted via electronic
- mail to <[email protected]>, or via the "cadbug.sh" script.
- </para>
-</refsection>
+ <refmeta>
+ <refentrytitle>libfb - FrameBuffer Library</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class="source">BRL-CAD</refmiscinfo>
+ <refmiscinfo class="manual">BRL-CAD Libraries</refmiscinfo>
+ </refmeta>
+ <refnamediv xml:id="name">
+ <refname>libfb</refname>
+ <refpurpose>
+ multiple device, generic frame buffer library
+ </refpurpose>
+ </refnamediv>
+ <!-- body begins here -->
+ <refsection xml:id="libfbgeneric">
+ <info>
+ <title>Generic frame buffer routines</title>
+ </info>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef><function>FBIO</function>
*fb_open</funcdef>
+ <paramdef>*
<parameter>fbfile</parameter></paramdef>
+ <paramdef>int fb_close ( fbp ) FBIO *
<parameter>fbp</parameter></paramdef>
+ <paramdef>int fb_read ( fbp , x , y , addr ,
count ) FBIO * <parameter>fbp</parameter></paramdef>
+ <paramdef>RGBpixel
<parameter>*addr;</parameter></paramdef>
+ <paramdef>long
<parameter>count;</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int
<function>fb_write</function></funcdef>
+ <paramdef>*
<parameter>fbp</parameter></paramdef>
+ <paramdef>RGBpixel *
<parameter>addr</parameter></paramdef>
+ <paramdef>long
<parameter>count</parameter></paramdef>
+ <paramdef>int fb_rmap ( fbp , cmap ) FBIO *
<parameter>fbp</parameter></paramdef>
+ <paramdef>ColorMap *
<parameter>cmap</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int
<function>fb_wmap</function></funcdef>
+ <paramdef>*
<parameter>fbp</parameter></paramdef>
+ <paramdef>ColorMap *
<parameter>cmap</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int
<function>fb_clear</function></funcdef>
+ <paramdef>*
<parameter>fbp</parameter></paramdef>
+ <paramdef>RGBpixel *
<parameter>colorp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>char
*<function>fb_gettype</function></funcdef>
+ <paramdef>*
<parameter>fbp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int
<function>fb_getwidth</function></funcdef>
+ <paramdef>*
<parameter>fbp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int
<function>fb_getheight</function></funcdef>
+ <paramdef>*
<parameter>fbp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsection>
+ <refsection xml:id="libfbhardware">
+ <info>
+ <title>Hardware specific frame buffer routines</title>
+ </info>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>fb_cursor</function></funcdef>
+ <paramdef>* <parameter>fbp</parameter></paramdef>
+ <paramdef>int fb_scursor ( fbp , mode , x , y ) FBIO *
<parameter>fbp</parameter></paramdef>
+ <paramdef>int fb_setcursor ( fbp , bits , xbits , ybits
, xorig , yorig ) FBIO * <parameter>fbp</parameter></paramdef>
+ <paramdef>unsigned char
<parameter>bits</parameter>[]</paramdef>
+ <paramdef>int <parameter>xbits</parameter>,
<parameter>ybits</parameter>;</paramdef>
+ <paramdef>int <parameter>xorig</parameter>,
<parameter>yorig</parameter>;</paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>fb_window</function></funcdef>
+ <paramdef>* <parameter>fbp</parameter></paramdef>
+ <paramdef>int fb_zoom ( fbp , x , y ) FBIO *
<parameter>fbp</parameter></paramdef>
+ <paramdef>/ *Buffered frame buffer I/O: */ int
fb_ioinit ( fbp ) FBIO * <parameter>fbp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>fb_seek</function></funcdef>
+ <paramdef>* <parameter>fbp</parameter></paramdef>
+ <paramdef>void fb_tell ( fbp , xp , yp ) FBIO *
<parameter>fbp</parameter></paramdef>
+ <paramdef>int *xp , *
<parameter>yp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>fb_rpixel</function></funcdef>
+ <paramdef>* <parameter>fbp</parameter></paramdef>
+ <paramdef>RGBpixel *
<parameter>pixelp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>fb_wpixel</function></funcdef>
+ <paramdef>* <parameter>fbp</parameter></paramdef>
+ <paramdef>RGBpixel *
<parameter>pixelp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>fb_flush</function></funcdef>
+ <paramdef>* <parameter>fbp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>void <function>fb_log</function></funcdef>
+ <paramdef>format [ <parameter/></paramdef>
+ <paramdef>arg ] ... <parameter/></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsection>
+ <refsection xml:id="description">
+ <info>
+ <title>DESCRIPTION</title>
+ </info>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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 <emphasis
remap="B">RGBpixel</emphasis>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
+ <emphasis remap="B">RGBpixel</emphasis>
+ is thus the name of the <emphasis
remap="B">RGBpixel</emphasis>
+ itself, i.e. no ampersand is needed.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para><emphasis remap="I">Fb_open</emphasis> is used to open a
frame buffer
+ file <emphasis remap="I">fbfile</emphasis>. 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 <emphasis remap="I">fbfile</emphasis> is
+ <!-- B elided -->
+ <acronym>NULL</acronym> and the environment variable
+ <!-- B elided -->
+ <envar>FB_FILE</envar> is set, then the value of
<envar>FB_FILE</envar>
+ is used; otherwise the default frame buffer device for
the system is used.
+ See below for more details. The <emphasis
remap="I">width</emphasis>
+ and <emphasis remap="I">height</emphasis> 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.
+ </para>
+ <para><emphasis remap="I">Fb_close</emphasis> simply closes the
frame buffer.
+ </para>
+ <para><emphasis remap="I">Fb_read</emphasis> reads
+ <emphasis remap="I">count</emphasis> pixels from the
frame buffer
+ starting at the location specified by <emphasis
remap="I">x</emphasis>
+ and <emphasis remap="I">y</emphasis>, and places them
at program
+ memory address specified by <emphasis
remap="I">addr</emphasis>.
+ <emphasis remap="I">Fb_read</emphasis> returns the
number of
+ pixels actually read, or -1 on error.
+ </para>
+ <para><emphasis remap="I">Fb_write</emphasis> writes
+ <emphasis remap="I">count</emphasis> pixels from
program address
+ <emphasis remap="I">addr</emphasis> into the frame
buffer starting
+ at the location specified by <emphasis
remap="I">x</emphasis>
+ and <emphasis remap="I">y</emphasis>. <emphasis
remap="I">Fb_write</emphasis>
+ returns the number of pixels actually written, or -1 on
error.
+ </para>
+ <para><emphasis remap="I">Fb_rmap</emphasis>
+ reads in the color map from the frame buffer and
+ leaves at the location pointed to by
+ <emphasis remap="I">cmap</emphasis>.
+ </para>
+ <para><emphasis remap="I">Fb_wmap</emphasis>
+ writes the color map pointed to by
+ <emphasis remap="I">cmap</emphasis>
+ into the frame buffer. If the value of
+ <emphasis remap="I">cmap</emphasis>
+ is
+ <!-- B elided -->
+ <acronym>NULL</acronym>
+ then a linear color map is used as the default.
+ </para>
+ <para><emphasis remap="I">Fb_clear</emphasis>
+ 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.
+ </para>
+ <para><emphasis remap="I">Fb_gettype</emphasis>
+ returns a pointer to a string describing the frame
buffer
+ specified by the FBIO pointer.
+ </para>
+ <para><emphasis remap="I">Fb_getwidth</emphasis>
+ and <emphasis remap="I">Fb_getheight</emphasis>
+ returns the current size of the FBIO frame buffer.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para><emphasis remap="I">Fb_cursor</emphasis>
+ places the cursor at the image space coordinates given
by
+ <emphasis remap="I">x</emphasis>
+ and
+ <emphasis remap="I">y</emphasis>.
+ If the mode is non-zero, the cursor is made visible, and
+ if mode is zero, the cursor is turned off.
+ </para>
+ <para><emphasis remap="I">Fb_scursor</emphasis>
+ is the same as
+ <emphasis remap="I">fb_cursor</emphasis>
+ except that it
+ places the cursor at the
+ <emphasis remap="B">screen</emphasis>
+ space coordinates given by
+ <emphasis remap="I">x</emphasis>
+ and
+ <emphasis remap="I">y</emphasis>.
+ </para>
+ <para><emphasis remap="I">Fb_setcursor</emphasis>
+ 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 <emphasis
remap="I">bits</emphasis>
+ is a pointer to an array of unsigned chars containing
the bits of the cursor.
+ The arguments <emphasis remap="I">xbits</emphasis>
+ and <emphasis remap="I">ybits</emphasis>
+ specify the size of the cursor bitmap. The number of
bytes in the
+ <varname role="parameter">bits</varname> array will be
the width rounded
+ up to a multiple of eight (so that the cursor
"scanlines" are byte aligned)
+ times the height.
+ <varname role="parameter">bits</varname>[0]
+ is the lower left corner,
+ <varname role="parameter">bits</varname>[1]
+ is to the right of it, etc. The next line of the
+ <varname role="parameter">bits</varname>
+ array goes above the current one. Within a byte the
most significant
+ bit is the leftmost. The values
+ <emphasis remap="I">xorig</emphasis>
+ and <emphasis remap="I">yorig</emphasis>
+ 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.
+ </para>
+ <para><emphasis remap="I">Fb_window</emphasis>
+ sets the frame buffer window center position to the
image space coordinates
+ given by <emphasis remap="I">x</emphasis> and <emphasis
remap="I">y</emphasis>.
+ This command is usually used in conjunction with the
+ <emphasis remap="I">fb_zoom</emphasis> routine.
+ </para>
+ <para><emphasis remap="I">Fb_zoom</emphasis>
+ sets the zoom factor for the X coordinate to
+ <emphasis remap="I">x</emphasis>
+ and the zoom factor for the Y coordinate to
+ <emphasis remap="I">y</emphasis>.
+ Zooming is generally done by pixel replication in
hardware.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para><emphasis remap="I">Fb_ioinit</emphasis>
+ should be called before using any of the other buffered
I/O routines and
+ repeated whenever the frame buffer is reopened.
+ </para>
+ <para><emphasis remap="I">Fb_seek</emphasis>
+ 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 <emphasis
remap="I">fb_seek</emphasis>
+ after every read or write since both <emphasis
remap="I">fb_rpixel</emphasis>
+ and <emphasis remap="I">fb_wpixel</emphasis> 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.
+ </para>
+ <para><emphasis remap="I">Fb_tell</emphasis>
+ 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 <emphasis remap="I">xp</emphasis> and <emphasis
remap="I">yp</emphasis>.
+ </para>
+ <para><emphasis remap="I">Fb_rpixel</emphasis>
+ reads the pixel at the current frame buffer location
+ and returns it into the location specified
+ by <emphasis remap="I">pixelp</emphasis>.
+ </para>
+ <para><emphasis remap="I">Fb_wpixel</emphasis>
+ writes the pixel pointed to by <emphasis
remap="I">pixelp</emphasis>
+ at the current frame buffer location.
+ </para>
+ <para><emphasis remap="I">Fb_flush</emphasis>
+ caused any current buffered frame buffer pages to be
written out.
+ Unnecessary writes are avoided by the use of page
reference bits.
+ </para>
+ <para>
+ The following is a printing routine which this library
uses to
+ indicate errors.
+ </para>
+ <para><emphasis remap="I">Fb_log</emphasis> will convert,
format and print its
+ <emphasis remap="I">args</emphasis> under control of
+ <emphasis remap="I">format</emphasis> to the standard
error output.
+ For more detailed information on the specification of
the control string,
+ see
<citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3S</manvolnum></citerefentry>.
+ This function may be supplied by the application if
different behavior
+ is desired.
+ </para>
+ </refsection>
+ <refsection xml:id="fb_file_devices">
+ <info>
+ <title>FB_FILE DEVICES</title>
+ </info>
+ <para>
+ 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.
+ </para>
+ <variablelist remap="TP">
+ <varlistentry>
+ <term>
+ <filename>/dev/debug</filename>
+ <emphasis remap="I">[num]</emphasis>
+ </term>
+ <listitem>
+ <para>The "/dev/debug" interface prints
one line to logs each call
+ to the frame buffer library.
+ <!-- .br -->
+ <emphasis
remap="I">num</emphasis>
+ is a bitvector indicating the
levels of verbosity of the output. See
+ <emphasis
remap="B">fb.h</emphasis>
+ for the bit definitions.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap="I">filename</emphasis>
+ </term>
+ <listitem>
+ <para>Disk file interface</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap="B">hostname:</emphasis>
+ <emphasis
remap="I">[devicename]</emphasis>
+ </term>
+ <listitem>
+ <para>TCP-based network links to a
remote framebuffer, where
+ <emphasis
remap="I">devicename</emphasis>
+ is any from this list, for
example,
+ fictitious.brlcad.org:/dev/ik0
or fictitious.brlcad.org:/dev/sgi.
+ A <emphasis
remap="B">hostname</emphasis>
+ with a null<emphasis
remap="I">devicename</emphasis>
+ 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.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsection>
+ <refsection xml:id="examples">
+ <info>
+ <title>EXAMPLES</title>
+ </info>
+ <para><emphasis remap="I">Libfb</emphasis>
+ can be loaded with any C program:
+ </para>
+ <synopsis>
+ $  <filename>/bin/cc  program.c
 -lfb -l\<system-library...\></filename>
+ </synopsis>
+ <para>
+ where <emphasis
remap="I"><system-library></emphasis>
+ 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.
+ </para>
+ </refsection>
+ <refsection xml:id="return_values">
+ <info>
+ <title>RETURN VALUES</title>
+ </info>
+ <para><emphasis remap="I">fb_close</emphasis>,
+ <emphasis remap="I">fb_write</emphasis>,
+ <emphasis remap="I">fb_read</emphasis>,
+ <emphasis remap="I">fb_wmap</emphasis>,
+ <emphasis remap="I">fb_rmap</emphasis>,
+ <emphasis remap="I">fb_clear</emphasis>,
+ <emphasis remap="I">fb_cursor</emphasis>,
+ <emphasis remap="I">fb_scursor</emphasis>,
+ <emphasis remap="I">fb_setcursor</emphasis>,
+ <emphasis remap="I">fb_window</emphasis>,
+ <emphasis remap="I">fb_zoom</emphasis>,
+ <emphasis remap="I">fb_ioinit</emphasis>,
+ <emphasis remap="I">fb_seek</emphasis>,
+ <emphasis remap="I">fb_wpixel</emphasis>,
+ <emphasis remap="I">fb_rpixel</emphasis>
+ and
+ <emphasis remap="I">fb_flush</emphasis>
+ return -1 to indicate failure.
+ <emphasis remap="I">Fb_open</emphasis>
+ returns FBIO_NULL to indicate failure, and a non-null
FBIO structure pointer
+ upon success.
+ <emphasis remap="I">fb_read</emphasis>,
+ and
+ <emphasis remap="I">fb_write</emphasis>
+ return the number of pixels actually read or written.
+ <emphasis remap="I">fb_gettype</emphasis>
+ returns a pointer to a NULL terminated description
string.
+ </para>
+ </refsection>
+ <refsection xml:id="see_also">
+ <info>
+ <title>SEE ALSO</title>
+ </info>
+
<para><citerefentry><refentrytitle>fbhelp</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>brlcad</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
+ </refsection>
+ <refsection xml:id="author">
+ <title>AUTHOR</title>
+ <para>BRL-CAD Team</para>
+ </refsection>
+ <refsection xml:id="bug_reports">
+ <info>
+ <title>BUG REPORTS</title>
+ </info>
+ <para>
+ Reports of bugs or problems should be submitted via
electronic
+ mail to <[email protected]>, or via the "cadbug.sh"
script.
+ </para>
+ </refsection>
</refentry>
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
Keep yourself connected to Go Parallel:
INSIGHTS What's next for parallel hardware, programming and related areas?
Interviews and blogs by thought leaders keep you ahead of the curve.
http://goparallel.sourceforge.net
_______________________________________________
BRL-CAD Source Commits mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/brlcad-commits
