# LIBDM

Robert G. Parker
Mark L. Ulferts

        mulferts@austin.dsccc.com

## Preface

LIBDM provides the API for accessing BrlCad's display managers. Display managers can be thought of as configurable drawing machines that grind away on generic drawing commands called vlists resulting in display manager specific drawing actions. Vlists are capable of specifying points, lines and polygons in 3D. Display managers are also capable of drawing 2D points, lines, and strings.

The following DM (display manager) types are supported:

Key Frame

DM Type | Canvas Type
--- | ---
X | X window
ogl | mixed X/OpenGL window
ps | postscript file
plot | unix plot file

## Application Programming Interface

### LIBDM's Application Programming Interface

struct dm * DM_OPEN ( int dtype, int argc, char *argv[] )

DM_OPEN creates a display manager of type dtype and returns a pointer to its dm structure. argc and argv are passed to dm_processOptions for interpretation. DM_NULL is returned if unable to acquire a display manager.

        int dtype;
        int argc;
        char *argv[];
        struct dm *dmp;

        /*
         * Open a 512x512 X display manager window on the local
         * display using my_default_bindings to set default key
         * and mouse button bindings.
         */
        dtype = DM_TYPE_X;
        argv[0] = "X_open";
        argv[1] = "-i";
        argv[2] = "my_default_bindings";
        argv[3] = "-S";
        argv[4] = "512";
        argv[5] = "-d";
        argv[6] = ":0";
        argv[7] = (char *)NULL;
        dmp = DM_OPEN(dtype, argc, argv);

int DM_CLOSE ( struct dm *dmp )

DM_CLOSE closes the display manager indicated bydmp.

                /* open a display manager */
        dmp = DM_OPEN(dtype, argc, argv);

                  .  .  .

        /* close the display manager */
        DM_CLOSE(dmp);

int DM_DRAW_BEGIN( struct dm *dmp )

DM_DRAW_BEGIN prepares the display manager indicated by dmp for a round of drawing.

                /* begin another drawing sequence */
        (void)DM_DRAW_BEGIN(dmp);

int DM_DRAW_END ( struct dm *dmp )

DM_DRAW_END ends the drawing sequence for the display manager indicated by dmp. This should be called before the next call to DM_DRAW_BEGIN in order to see the results of the current drawing sequence.

              /* end the current drawing sequence */
        (void)DM_DRAW_END(dmp);

int DM_NORMAL ( struct dm *dmp )

DM_NORMAL restores the display manager indicated by dmp to a normal mode of operation (i.e. not scaled, rotated, displaced, etc.).

                /* restore to normal mode */
        (void)DM_NORMAL(dmp);

int DM_LOADMATRIX ( struct dm *dmp, mat_t mat, int which_eye )

DM_LOADMATRIX loads the display manager indicated by dmp with a new transformation matrix. mat indicates the matrix to be loaded. which_eye denotes the eye the matrix applies to and can have a value of 0 to indicate non-stereo, a value of 1 to indicate the right eye, or a value of 2 to indicate the left eye.

                  /* load the display manager with mat --- not using stereo */
        (void)DM_LOADMATRIX(dmp, mat, 0);

int DM_DRAW_STRING_2D ( struct dm *dmp, char *str, int x, int y, int size, int use_aspect )

DM_DRAW_STRING_2D draws a string in the display manager window indicated by dmp. str is a pointer to the string to be drawn. x and y indicate where to begin drawing the string and are expected to be in the range [-2048,2047]. The size argument indicates the font size to use (currently used only by dm-ps). The expected values for size are 0 for small, 1 for medium, 2 for large, and 3 for huge. use_aspect indicates whether to use the aspect ratio to modify the starting point where the string will be drawn.

              /*
         * - draw the string starting at the lower left corner
         * - use the small font
         * - don't use aspect ratio to modify string placement
         */
        (void)DM_DRAW_STRING_2D(dmp, "starting string at lower left", -2040, -2040, 0, 0)

int DM_DRAW_LINE_2D ( struct dm *dmp, int x1, int y1, int x2, int y2 )

DM_DRAW_LINE_2D is used to draw two-dimensional lines in the display manager window indicated by dmp. x1, y1, x2, and y2 indicate the coordinates for the line to be drawn.

              /* draw a line from the lower left corner of the window to the upper right corner */
        (void)DM_DRAW_LINE_2D(dmp, -2048, -2048, 2047, 2047);

int DM_DRAW_POINT_2D ( struct dm *dmp, int x, int y )

DM_DRAW_POINT_2D draws a point in the display manager window indicated by dmp. x and y indicate the coordinates for the point to be drawn.

              /* draw a yellow dot in the center of the window */
        (void)DM_SET_FGCOLOR(dmp, 230, 230, 0, 1);
        (void)DM_DRAW_POINT_2D(dmp, 0, 0);

int DM_DRAW_VLIST ( struct dm *dmp, struct rt_vlist *vp )

DM_DRAW_VLIST takes the vlist pointer vp and interprets it for drawing into the display manager window indicated by dmp .

              /* draw the vlists pointed to by view_list_ptr */
        (void)DM_DRAW_VLIST(dmp, view_list_ptr);

int DM_SET_FGCOLOR ( struct dm *dmp, short r, short g, short b, int strict )

DM_SET_FGCOLOR sets the color for drawing in the display manager indicated by dmp. r, g, and b denote the color and have values in the range [0,255]. Strict specifies to really use this color (i.e. don't allow ogl to do fancy things with the color when depth cueing).

              /* set the drawing color to red */
        (void)DM_SET_FGCOLOR(dmp, 220, 0, 0, 1);

int DM_SET_BGCOLOR ( struct dm *dmp, short r, short g, short b )

DM_SET_BGCOLOR sets the background color for the display manager indicated by dmp. r, g, and b denote the color and have values in the range [0,255].

              /* set the background color to red */
        (void)DM_SET_BGCOLOR(dmp, 220, 0, 0);

int DM_GET_BGCOLOR ( struct dm *dmp, Tcl_Interp *interp )

DM_SET_BGCOLOR gets the background color for the display manager indicated by dmp and places the result in interp.

              /* get the background color */
        return DM_GET_BGCOLOR(dmp, interp);

int DM_SET_LINE_ATTR ( struct dm *dmp, int width, int style )

DM_SET_LINE_ATTR sets the display managers (i.e. dmp) line width to width and sets its line style to style . Currently, there are only 2 valid values for style: 0 for solid lines and 1 for dashed lines.

              /* set the display manager up to draw fat dashed lines */
        (void)DM_SET_LINE_ATTR(dmp, 10, 1);

int DM_SET_WIN_BOUNDS ( struct dm *dmp, int clip[6] )

DM_SET_WIN_BOUNDS sets the view clipping planes for the display manager indicated by dmp. clip is interpreted as follows: {XMIN, XMAX, YMIN, YMAX, ZMIN, ZMAX}

              int clip[6] = { -2048, 2047, -2048, 2047, -2048, 2047 };

        /* set the display managers clipping planes */
        (void)DM_SET_WIN_BOUNDS(dmp, clip);

int DM_ENDDLIST ( struct dm *dmp )

DM_ENDDLIST ends the definition of the display list currently being defined for the display manager indicated by dmp.

              /* define display list 1 to draw objects */
        (void)DM_BEGINDLIST(dmp, 1);

        /* Put code to draw objects here */

        (void)DM_ENDDLIST(dmp);

int DM_DRAWDLIST ( struct dm *dmp, unsigned int list )

DM_DRAWDLIST draws the previously defined display list list in the display manager indicated by dmp.

              unsigned int i;

        /* draw display lists 1 through 9 */
        for (i = 1; i < 10; ++i)
           (void)DM_DRAWDLIST(dmp, i);

int DM_FREEDLISTS ( struct dm *dmp, unsigned int list, int range )

DM_FREEDLISTS frees the display lists indicated by list and range. list indicates the display list to start with and range indicates the number of display lists to be freed.

           /* free display lists 10 through 29 */
        (void)DM_FREEDLISTS(dmp, 10, 20);

### LIBDM's Other Support Routines

int dm_share_list ( struct dm *dmp1, struct dm *dmp2 )

dm_share_dlist provides a way to (un)share display lists. If dmp1 and dmp2 are not NULL, dmp1 will share its display lists with dmp2. If dmp2 is NULL, dmp1 will no longer share its display lists.

void dm_fogHint ( struct dm *dmp, int fastfog )

dm_fogHint is used to give a hint to the display manager about whether to use an efficient fog calculation method or the most accurate. Note - this is currently only implemented by the ogl display manager.

                  /* use the most efficient method for calculating fog */
        dm_fogHint(dmp, 1);

        /* use the most accurate method for calculating fog */
        dm_fogHint(dmp, 0);

int dm_limit ( val )

dm_limit takes an integer argument and returns zero if (NOISE <= val < = NOISE) where NOISE is the size of the dead spot around zero. If ( val < -NOISE ), the return value is ( val + NOISE ). If ( NOISE < val ), the return value is ( val - NOISE ).

                  /* The examples below assume that NOISE is 16 */

        /* i = 0 */
        i = dm_limit(16);

        /* i = 1 */
        i = dm_limit(17);

        /* i = 0 */
        i = dm_limit(-16);

        /* i = -1 */
        i = dm_limit(-17);

int dm_unlimit ( val )

dm_unlimit takes an integer value and returns zero if ( val == 0 ). If ( 0 < val ), the return value is ( NOISE + val ). If ( val < 0 ), the return value is ( -NOISE + val ). In short, dm_unlimit puts NOISE back into val.

                /* i = 0 */
        i = dm_unlimit(0);

        /* i = 17 */
        i = dm_unlimit(1);

        /* i = -17 */
        i = dm_unlimit(-1);

fastf_t dm_wrap ( val )

dm_wrap wraps val into the range [-1.0, 1.0].

                  /* f = 0.9 */
        f = dm_wrap(0.9);

        /* f = -0.5 */
        f = dm_wrap(1.5);

        /* f = 0.0 */
        f = dm_wrap(6.0);

        /* f = 1.0 */
        f = dm_wrap(7.0);

        /* f = 0.5 */
        f = dm_wrap(-1.5);

        /* f = -1.0 */
        f = dm_wrap(-5.0);

int dm_processOptions(struct dm *dmp, struct bu_vls *vls, int argc, char *argv[])

dm_processOptions is used primarily by LIBDM's display manager open routines to process options. The table below lists the available options. Note - the application would not typically call processOptions. The application would instead build the desired options into the argv list that is supplied to the call to DM_OPEN.

Key Frame

Options | Description
--- | ---
-d string | This option specifies where to draw the display manager. string is expected to be in the same form as the X DISPLAY environment variable.
-i init_script | This option specifies a Tcl script to use to initialize the display manager.
-N height | This option specifies the number of scanlines or height to make the display manager window.
-n name | This option specifies a name to use for the display manager.
-S size | This option specifies the display manager windows square size.
-s | This option turns on stereo mode and is currently only available with the ogl display manager.
-t 0|1 | This option specifies whether the display manager window will be a top level window or an embedded window. A non-zero value indicates a top level window, while zero indicates an embedded window.
-W width | This option specifies the width in pixels of the display manager window.

void dm_configureWindowShape ( dmp )

dm_configureWindowShape is used to update the internal state of a display manager after its window has been newly created or resized. This routine is typically called by an event handler.

void dm_zbuffer ( struct dm *dmp, zbuffer_on )

dm_zbuffer is used to turn Z-buffering on/off. Note - zbuffering is only supported by the ogl display manager.

                  /* turn zbuffering on */
        dm_zbuffer(dmp, 1);

void dm_lighting ( struct dm *dmp, int lighting_on )

dm_lighting is used to turn lighting on/off. Note - lighting is only supported by the ogl display manager.

                  /* turn lighting on */
        dm_lighting(dmp, 1);

fastf_t dm_Xx2Normal ( struct dm *dmp, int x )

dm_Xx2Normal takes x in X screen coordinates and returns a value in the range [-1.0, 1.0]. dmp indicates the display manager of interest.

fastf_t dm_Xy2Normal ( struct dm *dmp, int y, int use_aspect )

dm_Xy2Normal takes y in X screen coordinates and returns a value in the range [-1.0, 1.0]. dmp indicates the display manager of interest. use_aspect specifies whether to use the window's aspect ratio in the calculation.

int dm_Normal2Xx ( struct dm *dmp, fastf_t x )

dm_Normal2Xx takes x in normalized coordinates and returns a value in X screen coordinates. dmp indicates the display manager of interest

int dm_Normal2Xy ( struct dm *dmp, fastf_t y )

dm_Normal2Xy takes y in normalized coordinates and returns a value in X screen coordinates. dmp indicates the display manager of interest.

int Dm_Init ( Tcl_Interp *interp )

Dm_Init initializes LIBDM's tcl commands. interp indicates the Tcl interpreter.

### LIBDM's Tcl Interface

dm_bestXType display

dm_bestXType returns the best available display manager type that can be used on the X server indicated by display. Display is specified the same and has the same meaning as the X DISPLAY environment variable.

dm_validXType display dtype

dm_validXType returns 1 if dtype is a valid display manager type for the X server indicated by display. Otherwise, 0 is returned. Display is specified the same and has the same meaning as the X DISPLAY environment variable.

## Display Manager Objects

### NAME

dm_open - create and manipulate a display manager object.

### SYNOPSIS

dm_open [ pathName type [options]]

### COMMAND LINE OPTIONS

Option:

-N height

Specifies the window's height (i.e. number of raster lines).

Option:

-W width

Specifies the window's width.

Option:

-S size

Specifies the window's square size (i.e. width and height).

Option:

-i initproc

Specifies the initialization proc. This proc is called with the pathName as an argument.

Option:

-t 0|1>

Specifies the toplevel flag. 0 indicates the display manager object is an internal window, while 1 indicates a toplevel window.

Option:

-d dpy

Specifies the display string in a format understood by X windows.

### DESCRIPTION

The dm_open command creates a new window (given by the pathName argument) and makes it into a display manager object for displaying geometry. Additional options, described above, may be specified on the command line to configure aspects of the display manager object. The dm_open command returns its pathName argument. At the time this command is invoked, there must not exist a window named pathName, but pathName's parent must exist.

### METHODS

The dm_open command creates a new Tcl command whose name is pathName. This command may be used to invoke various operations on the display manager object. It has the following general form:

pathName option ?arg arg ...?

Option and the args determine the exact behavior of the command. The following commands are possible for display manager objects:

pathName bg ["r g b"]

Set/get the background color. The rgb components are expected to be integers between 0 and 255. pathName bounds [xmin xmax ymin ymax zmin zmax]

Set/get the window bounds. Some display managers use this to calculate clipping planes (i.e. X).

pathName clear

Clear the drawing area using the background color.

pathName close

Close the display manager object.

pathName configure

Called to handle Configure events.

pathName debug [0|1]

Set/get debug mode. 0 indicates debugging is off while 1 indicates debugging is on.

pathName drawBegin

Begin the drawing sequence.

pathName drawEnd

End the drawing sequence. This will cause the graphics pipe to be flushed.

pathName drawGeom geo_obj(s)

Draw one or more drawable geometry objects.

pathName drawLine x1 y1 x2 y2

Draw the 2D line indicated by endpoints (x1, y1) and (x2, y2). The given coordinates are expected to be in the range [-1, 1].

pathName drawPoint x y

Draw the 2D point at position (x, y).

pathName drawSList slp

Draw the solid list specified by the solid list pointer (i.e.slp).

pathName drawString str x y size use_aspect

Draw the 2D string starting at position (x, y). The x and y coordinates are expected to be in the range [-1, 1]. The size is currently ignored. The use_aspect flag indicates whether or not to use the aspect ratio to modify the starting position.

pathName drawVList vlp

Draw the vector list specified by the vector list pointer (i.e.vlp).

pathName fg ["r g b"]

Set/get the foreground color. The rgb components are expected to be integers between 0 and 255.

pathName flush

Flushes the X server's request buffer.

pathName get_aspect

Get the window's aspect ratio (i.e. width / height).

pathName light [0|1]

Set/get light mode. 0 indicates light is off while 1 indicates light is on.

pathName linestyle [0|1]

Set/get linestyle. 0 indicates solid lines while 1 indicates dashed lines.

pathName linewidth [width]

Set/get linewidth. This setting determines how fat to draw the wireframe lines.

pathName listen [port]

Set/get the port used to listen for framebuffer clients. Port values less than zero turn off listening.

pathName loadmat mat

Load the matrix, mat, into the display manager. This is typically a model2view matrix.

pathName normal

Restore display manager to a normal mode of operation (i.e. not scaled, rotated, displaced, etc.).

pathName observer [subcommand]

This command is used to maintain a list of observers. Observers are objects who have registered an interest in when this display manager object receives pixels in its role as a framebuffer server. Whenever pixel data is received the observers on the list are notified.

pathName observer attach obs [command]

Add the specified observer, obs, to the list of observers. If command is specified then it is executed each time pixel data is received. Otherwise, the observer is expected to have an update method which is called with the name of this display manager object as an argument.

pathName observer detach obs

Remove the specified observer, obs, from the list of observers.

pathName observer show

Return the list of observers for this display manager object.

pathName perspective [0|1]

Set/get perspective mode. 0 indicates perspective is off, while 1 indicates perspective is on.

pathName refreshfb

Draws/displays the pixels stored in the widget's framebuffer.

pathName size [width height]

Set/get the window size.

pathName sync

Flushes the X server's request buffer and waits until all events have been processed.

pathName zbuffer [0|1]

Set/get zbuffer mode. 0 indicates that zbuffer is off, while 1 indicates zbuffer is on.

pathName zclip [0|1]

Set/get zclipping mode. 0 indicates zclipping is off, while 1 indicates zclipping is on.

    The following sequence creates a display manager object and draws two yellow lines that connect the opposite corners of the window.
    cwish> dm_open .d X -t 0 -s 400
    .d
    cwish> pack .d -expand yes -fill both
    cwish> .d drawBegin
    cwish> .d fg "255 255 0"
    cwish> .d drawLine -1 1 1 -1
    cwish> .d drawLine -1 -1 1 1
    cwish> .d drawEnd

## Generic frame buffer routines

`fb` *fb_open * fbfile int fb_close ( fbp ) fb * fbp int fb_read ( fbp , x , y , addr , count ) fb * fbp RGBpixel *addr; long count; int `fb_write` * fbp RGBpixel * addr long count int fb_rmap ( fbp , cmap ) fb * 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 ) fb * fbp int fb_setcursor ( fbp , bits , xbits , ybits , xorig , yorig ) fb * fbp unsigned char bits[] int xbits, ybits; int xorig, yorig; int `fb_window` * fbp int fb_zoom ( fbp , x , y ) fb * fbp / *Buffered frame buffer I/O: */ int fb_ioinit ( fbp ) fb * fbp int `fb_seek` * fbp void fb_tell ( fbp , xp , yp ) fb * 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 (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.

`/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 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.