NAME

fb − NEWS frame buffer device interface

SYNOPSIS

fb0 at iop addr ffe5d0 intr 44

/dev/fb

#include <newsiop/framebuf.h>

DESCRIPTION

The fb interface provides access to the NEWS frame buffer device. The black and white bitmap display has a 2048x2048 pixel frame buffer, of which 816x1024 are displayed. In the case of the color bitmap display, the frame buffer is 2048x1024 pixels, 1280x1024 of which are displayed. This frame buffer interface enables reading and writing of data, raster operations, drawing lines, etc. 

The operations are carried out using the ioctl(2) system call. The ioctl call provides for operations on user-defined (user-space) bitmaps, as well as frame buffer operations. 

COLOR

The color bitmap display’s frame buffer consists of 4 (or 8) planes, so that 16 (or 256) colors can be displayed simultaneously. The 3 values for red, green and blue are made up of 4 (or 8) bits each, so that the user may choose from 4096 (or 16 million) colors in the color palette. 

DATA TYPES

The following data structures are used for bitmap operations. 

 typedef unsigned shortWord;
 #define BitsPerWord16
 typedef struct {
shortx, y;
} sPoint;
 typedef struct {
sPointorigin;
sPointextent;
} sRectangle;
 typedef struct {
char type;/∗ BM_FB, BM_MEM or BM_0 ∗/
char depth;/∗ bitmap depth ∗/
unsigned short width;/∗ width in Words ∗/
sRectangle rect;/∗ defined area ∗/
Word ∗base;/∗ for BM_MEM ∗/
} sBitmap;
 #define BM_FB0/∗ frame buffer ∗/
#define BM_MEM1/∗ bitmap in memory (XY format) ∗/
#define BM_02/∗ virtual bitmap of data ’0’ ∗/
 

Word is defined as an unsigned 16-bit (1 word) quantity. 

The sPoint structure is used for points. 

The sRectangle structure is used for upright rectangles, where origin is the upper-left corner, and extent indicates the width and height of the rectangle. 

The sBitmap structure is used to define bitmaps. The type field indicates whether the bitmap is in main memory or in the frame buffer.  BM_FB is for bitmaps in the frame buffer, while BM_MEM is for bitmaps in main memory. BM_MEM bitmaps are stored in the XY format, which means that the data for plane 0 follows that for plane 1, and so on.  BM_0 is for virtual bitmaps whose data is all 0.  BM_0 bitmap can be used only as a source bitmap at raster operation.  The depth field gives the depth of the bitmap. A black and white frame buffer bitmap has a depth of 1, while a color frame buffer bitmap can have a depth of 4 or 8 planes.  A bitmap in main memory or a BM_0 bitmap can have a depth of 1, 4 or 8, whether or not a color display is used. 

The width of a BM_MEM bitmap gives the number of words in the X direction. The width does not have to be specified for BM_FB and BM_0 bitmaps. 

The rect field gives the size of the bitmap. It is only possible to carry out operations within this area. 

The base field points at the start of the data. 

In the case of a BM_MEM bitmap, the data has to be aligned at a word boundary. The first bit of the first word of the first row corresponds to the point rect.origin. This means that a bitmap with a depth of 1 requires (width ∗ rect.extent.y) words, where width is just large enough to contain rect.extent.x bits. 

IOCTL

FBIOCSETDIM

FBIOCGETDIM
These requests allow the user to set or inquire the brightness of a black and white display. The dimmer level varies from 0 to 3, where 0 is the brightest and the default. These requests are not supported for color displays.

 intdimmer_level;
ioctl(fildes, FBIOCSETDIM, &dimmer_level);
ioctl(fildes, FBIOCGETDIM, &dimmer_level);
 

FBIOCSETSCRMODE

FBIOCGETSCRMODE
The user issues these requests to set or inquire the screen mode, which can be BLACK_ON_WHITE (default), or WHITE_ON_BLACK. In the BLACK_ON_WHITE mode, 1 is black and 0 is white, while the opposite is true in the WHITE_ON_BLACK case. These requests are not supported at this time. 

 /∗
 ∗ set screen mode
 ∗/
 #define BLACK_ON_WHITE0/∗ white − 0, black − 1 (default) ∗/
#define WHITE_ON_BLACK1/∗ white − 1, black − 0 ∗/
 intscrmode;
ioctl(fildes, FBIOCSETSCRMODE, &scrmode);
ioctl(fildes, FBIOCGETSCRMODE, &scrmode);
 

FBIOCBITBLT
This request is for two-operand raster operations (bitblt). The source and destination bitmaps may be in main memory or in the frame buffer. BM_0 bitmap can be used only as a source. The depths of the source and destination bitmaps must be equal or the depth of one of the bitmaps must be 1.

 /∗ 2 operand bitblt ∗/
typedef struct {
unsigned charfunc;/∗ function code ∗/
chartransp;/∗ transparency ∗/
intfore_color;/∗ foreground color ∗/
intaux_color;/∗ auxiliary color ∗/
intplanemask;/∗ select plane ∗/
sBitmapsrcBitmap;/∗ source bitmap ∗/
sRectanglesrcRect;/∗ source rectangle ∗/
sBitmapdestBitmap;/∗ destination bitmap ∗/
sRectangledestClip;/∗ clip rectangle ∗/
sPointdestPoint;/∗ destination point ∗/
} sBitblt;
 /∗ func ∗/
#define BF_00x0/∗ 0 ∗/
#define BF_SDA0x1/∗ Src & Dest ∗/
#define BF_SDIA0x2/∗ Src & ~Dest ∗/
#define BF_S0x3/∗ Src ∗/
#define BF_SIDA0x4/∗ ~Src & Dest ∗/
#define BF_D0x5/∗ Dest ∗/
#define BF_SDX0x6/∗ Src ^ Dest ∗/
#define BF_SDO0x7/∗ Src | Dest ∗/
#define BF_SDOI0x8/∗ ~(Src | Dest) ∗/
#define BF_SDXI0x9/∗ ~(Src ^ Dest) ∗/
#define BF_DI0xa/∗ ~Dest ∗/
#define BF_SDIO0xb/∗ Src | ~Dest ∗/
#define BF_SI0xc/∗ ~Src ∗/
#define BF_SIDO0xd/∗ ~Src | Dest ∗/
#define BF_SDAI0xe/∗ ~(Src & Dest) ∗/
#define BF_10xf/∗ 1 ∗/
 /∗ Plane Mask ∗/
#define FB_PLANEALL0xff
#define FB_PLANE00x1
#define FB_PLANE10x2
#define FB_PLANE20x4
#define FB_PLANE30x8
#define FB_PLANE40x10
#define FB_PLANE50x20
#define FB_PLANE60x40
#define FB_PLANE70x80
 

The sBitblt structure is used for the parameters.  The func field indicates the function code of the raster operation. The transp field is the transparency, and can be 0 or 1. If it is 1, then the destination pixels corresponding to source pixels that are 0 will not be affected. 

The fore_color and aux_color fields are meaningless unless the depth of the source bitmap is 1.  Source bits that have the value 1 are taken to be (the bit pattern corresponding to) the fore-color before performing the operation together with the corresponding destination pixel. On the other hand, the bitblt pretends that 0 source bits are the aux-color while performing the function. For example, if the func is BF_S (copy source to destination) then the pixels corresponding to source bits that have the value 1 are displayed in the fore-color, while the other pixels appear in the aux-color. 

The planemask field specifies which planes to use during the operation. A 1 in the planemask tells the bitblt to involve the corresponding plane in the operation, whereas a 0 would indicate that that plane is to be ignored. Bit N corresponds to plane N. 

The fields srcBitmap and srcRect indicate which source bitmap is to be used in the operation. 

The fields destBitmap and destPoint specify the destination bitmap. The destPoint is the upper-left corner, and the size of the rectangle in which raster operations will occur is the same as the srcRect.  The field destClip is used to specify which part of the destination is to be clipped. 

 sBitbltbitblt;
ioctl(fildes, FBIOCBITBLT, &bitblt);
 

FBIOCBATCHBITBLT
This request is used to carry out a number of bitblt operations in one go (in a batch). The source and destination bitmaps are the same for each operation but the source rectangle and the destination point may be different each time.

 typedef struct {
sRectanglesrcRect;/∗ source rectangle ∗/
sPointdestPoint;/∗ destination point ∗/
} sSrcDest;
  /∗
 ∗ batch bitblt
 ∗/
typedef struct {
unsigned charfunc;/∗ function code ∗/
chartransp;/∗ transparency ∗/
intfore_color;/∗ foreground color ∗/
intaux_color;/∗ auxiliary color ∗/
intplanemask;/∗ select plane ∗/
sBitmapsrcBitmap;/∗ source bitmap ∗/
sBitmapdestBitmap;/∗ destination bitmap ∗/
sRectangledestClip;/∗ clip rectangle ∗/
intnSrcDest;/∗ number of src-dest in list ∗/
sSrcDest∗srcDestList;/∗ pointer to src-dest spec ∗/
} sBatchBitblt;
 #define MAX_BATCHBITBLT1024/∗ max number in src-dest list ∗/
 

The sBatchBitblt structure contains source and destination bitmaps similar to the ones in the sBitblt structure. The srcDestList field points at a list of source rectangles and destination points, the number of elements being given by the nSrcDest field. 

 sBatchBitbltbbitblt;
ioctl(fildes, FBIOCBATCHBITBLT, &bbitblt);
 

FBIOCTILEBITBLT
This request is used for ‘pattern tiling’ raster operations.

 /∗ tile 2 operand bitblt ∗/
typedef struct {
unsigned charfunc;/∗ function code ∗/
chartransp;/∗ transparency ∗/
intfore_color;/∗ foreground color ∗/
intaux_color;/∗ auxiliary color ∗/
intplanemask;/∗ select plane ∗/
sBitmapptnBitmap;/∗ pattern bitmap ∗/
sRectangleptnRect;/∗ pattern rectangle ∗/
sPointrefPoint;/∗ reference point ∗/
sBitmapdestBitmap;/∗ destination bitmap ∗/
sRectangledestClip;/∗ clip rectangle ∗/
sRectangledestRect;/∗ destination rectangle ∗/
} sTileBitblt;
 

The sTileBitblt structure is used to pass the parameters. The ptnBitmap and ptnRect fields specify the pattern to be used. The refPoint field indicates the reference point for the tiling operation. This means that the reference point and the upper-left corner of the pattern are made to coincide on the destination bitmap. The reference point may be outside the destination rectangle or destination clip rectangle. 

 sTileBitblttbitblt;
ioctl(fildes, FBIOCTILEBITBLT, &tbitblt);
 

FBIOCPOLYLINE
This requests allows the user to draw polylines. The user is free to specify any line color, line pattern and raster operation function code.

 /∗ line ∗/
typedef struct {
unsigned intlptn;/∗ line pattern ∗/
shortnp;/∗ number of points ∗/
sPoint∗plist;/∗ point list ∗/
intfore_color;/∗ foreground color ∗/
intaux_color;/∗ auxiliary color ∗/
intplanemask;/∗ select plane ∗/
chartransp;/∗ transparency ∗/
unsigned charfunc;/∗ rop function code ∗/
chardlpf;/∗ draw last point flag ∗/
sRectangleclip;/∗ clip rectangle ∗/
sBitmapdrawBM;/∗ drawing bitmap ∗/
} sPrimLine;
 /∗ Line Pattern (sample) ∗/
#define LINE_SLD(unsigned)0xffffffff/∗ solid ∗/
#define LINE_DSH(unsigned)0xfcfcfcfc/∗ dash ∗/
#define LINE_DOT(unsigned)0xcccccccc/∗ dot ∗/
#define LINE_DSHDOT(unsigned)0xfff18fff/∗ dash dot ∗/
#define LINE_DSHDOTDOT(unsigned)0xff8c63ff/∗ dash dot dot ∗/
 

The sPrimLine structure is used for the polyline request.  A 32-bit line pattern can be specified using the lptn field.  The plist field is used to pass np points in the call. Note that np is the number of points and not the number of lines.  For an explanation of the fore_color, aux_color, planemask, transp and func fields, see FBIOCBITBLT.  The dlpf flag indicates whether or not to draw the last point in the list; if it is 0 the point is not drawn, otherwise it is drawn. A 0 in this field would probably be used if a closed figure is to be drawn. The drawBM and clip fields are used to specify the drawing bitmap and the clip rectangle respectively. 

 sPrimlineprimline;
ioctl(fildes, FBIOCPOLYLINE, &primline);
 

FBIOCDJPOLYLINE
This request is rather similar to the FBIOCPOLYLINE request. The latter is used to draw a continuous line, whereas this one is used to draw a disjoint line. The dlpf field is used to specify whether or not the end-points of each line segment are to be drawn. 

 sPrimlineprimline;
ioctl(fildes, FBIOCDJPOLYLINE, &primline);
 

FBIOCPOLYMARKER
This request draws polymarkers. Actually, this request allows one to carry out raster operations between a specified pattern and (several) bitmaps.

 /∗ marker ∗/
typedef struct {
shortnp;/∗ number of points ∗/
sPoint∗plist;/∗ point list ∗/
sRectangleptnRect;/∗ pattern rectangle ∗/
sBitmapptnBM;/∗ pattern bitmap ∗/
intfore_color;/∗ foreground color ∗/
intaux_color;/∗ auxiliary color ∗/
intplanemask;/∗ plane mask ∗/
chartransp;/∗ transparency ∗/
unsigned charfunc;/∗ rop function code ∗/
sRectangleclip;/∗ clip rectangle ∗/
sBitmapdrawBM;/∗ drawing bitmap ∗/
} sPrimMarker;
 

The sPrimMarker structure is used to draw a polymarker. The ptnBM and ptnRect fields specify which pattern is to used in the raster operation. The fields plist and np give the point list and number of points respectively. 

 sPrimMarkerprimmarker;
ioctl(fildes, FBIOCPOLYMARKER, &primmarker);
 

FBIOCRECTANGLE
An upright rectangle is filled with the given pattern.

 /∗ rectangle filling ∗/
typedef struct {
sRectanglerect;/∗ rectangle ∗/
sPointrefPoint;/∗ fill reference point ∗/
sRectangleptnRect;/∗ pattern rectangle ∗/
sBitmapptnBM;/∗ pattern bitmap ∗/
intfore_color;/∗ foreground color ∗/
intaux_color;/∗ auxiliary color ∗/
intplanemask;/∗ select plane ∗/
chartransp;/∗ transparency ∗/
unsigned charfunc;/∗ rop function code ∗/
sRectangleclip;/∗ clip rectangle ∗/
sBitmapdrawBM;/∗ drawing bitmap ∗/
} sPrimRect;
 

For this request, the sPrimRect structure is used. The rect field specifies the rectangle, while the ptnBM and ptnRect fields specify which pattern is to be used in the filling. The refPoint field contains the point which is made to coincide with the upper-left corner of the pattern. It is not necessary for the refPoint to lie within the rect and clip. 

 sPrimRectrect;
ioctl(fildes, FBIOCRECTANGLE, &rect);
 

FBIOCFILLSCAN
Pattern filling is performed along the given scan lines.

 /∗ scan line array ∗/
#define SSCANL
typedef struct {
shorty;
shortx0, x1;
} sScanl;
 /∗ pattern filling ∗/
typedef struct {
shortnscan;/∗ number of scan element ∗/
sScanl∗scan;/∗ scan line data ∗/
sPointrefPoint;/∗ fill reference point ∗/
sRectangleptnRect;/∗ pattern rectangle ∗/
sBitmapptnBM;/∗ pattern bitmap ∗/
intfore_color;/∗ foreground color ∗/
intaux_color;/∗ auxiliary color ∗/
intplanemask;/∗ select plane ∗/
chartransp;/∗ transparency ∗/
unsigned charfunc;/∗ rop function code ∗/
sRectangleclip;/∗ clip rectangle ∗/
sBitmapdrawBM;/∗ drawing bitmap ∗/
} sPrimFill;
 

The sScanl structure is used for the scan lines, while the sPrimFill structure is used to pass all the parameters. The scan field contains a pointer to the array of scan lines, and the nscan field indicates how many scan lines there are. The pattern is specified using the ptnBM and ptnRect fields.  Again, the refPoint is the reference point needed to anchor the upper-left corner of the pattern. 

 sPrimFillfill;
ioctl(fildes, FBIOCFILLSCAN, &fill);
 

FBIOCTEXT
A string is written in the specified font. The font to be used can be a font in a bitmap or a ROM font.

 /∗ text ∗/
typedef struct {
chartype;/∗ ROM-font, etc ∗/
shortlen;/∗ string length ∗/
unsigned char∗str;/∗ string ∗/
sPointp;
intdx, dy;/∗ vector (16bit left shifted) ∗/
charex_factor;/∗ expansion factor ∗/
sPointfp;/∗ bitmap font upper-left ∗/
shortwidth, height;/∗ font width, font height ∗/
shortcolumn;/∗ number of characters in a row ∗/
sBitmapfontBM;/∗ font bitmap ∗/
intfore_color;/∗ foreground color ∗/
intaux_color;/∗ auxiliary color ∗/
chartransp;/∗ transparency ∗/
unsigned charfunc;/∗ rop function code ∗/
sRectangleclip;/∗ clip rectangle ∗/
sBitmapdrawBM;/∗ drawing bitmap ∗/
} sPrimText;
 /∗ Bitmap Font Type ∗/
#define ROM_ASCII0
#define ROM_KANJI1
#define ASCII2
 

In order to write the text, the sPrimText structure must be used. The type field indicates which font to use:

ROM_ASCIIROM font (1 byte code)
ROM_KANJIROM font (JIS Kanji code)
ASCIIBitmap font (1 byte code)

The len field gives the length of the string in bytes. Kanji users should be aware that this is not the same as the number of characters. The str field is a pointer to the string of characters. The p field contains the point corresponding to the upper-left corner of the first character. The dx and dy fields indicate in which direction the string is to be written. For example, if the characters are to be written 26 dots to the right of the previous characters and the string is to be horizontal, then the following values are used: dx = 26 << 16; dy = 0. The ex_factor field indicates the horizontal expansion factor. For example, if it is 1 the normal width is used, if it is 2 the width is doubled. The fp, width, height, and column fields define the font bitmap. The upper-left corner of the font bitmap is given by fp, while the width and height of the characters are given by width and height. (The character size is constant; variable pitch fonts are not supported.) The column field contains the number of characters in a row. The fields first_chr and last_chr indicate the first and last characters that can be found in the font bitmap. 

 sPrimTexttext;
ioctl(fildes, FBIOCTEXT, &text);
 

FBIOCGETSCRTYPE
This request returns the bitmap display type.

 /∗
 ∗screen type
 ∗/
typedef struct {
shortcolorwidth;/∗ color palette width ∗/
shortplane;/∗ number of planes ∗/
sRectanglebufferrect;/∗ framebuffer region ∗/
sRectanglevisiblerect;/∗ visible screen region ∗/
} sScrType;
 

The sScrType structure is used to pass the parameters. The colorwidth field gives the number of bits that are used for each of the values for red, green and blue in the color palette. The width is either 4 or 8; if it is 4, the high-order 4 bits of the byte are used, and if it is 8, all 8 bits are used.  The plane field indicates the number of planes, which is 1 for black and white displays, 4 (or 8) for color displays. The bufferrect field gives the size of the frame buffer, and the visiblerect field indicates the visible portion of the frame buffer. 

 sScrTypescrtype;
ioctl(fildes, FBIOCGETSCRTYPE, &scrtype);
 

FBIOCGETPALETTE

FBIOCSETPALETTE
These requests enable reading and writing of the color palette data.

 /∗
 ∗color
 ∗/
typedef struct {
shortindex;/∗ palette number ∗/
struct {
shortr, g, b;
} rgb;
} sPalette;
 

The palette numbers vary from 0 to 15 (4 planes), or 0 to 255 (8 planes).  In the case of the FBIOCGETPALETTE request, the palette number is passed in the field index.  The rgb field will have been written after the call.  In the case of the FBIOCSETPALETTE request, both the index and the rgb fields are set by the user (rgb = red, green, blue). 

 sPalettepalette;
ioctl(fildes, FBIOCGETPALETTE, &palette);
ioctl(fildes, FBIOCSETPALETTE, &palette);
 

BUGS

FBIOCSETSCRMODE and FBIOCGETSCRMODE are not supported. 

FILES

/dev/fbframe buffer

NEWS-OSRelease 3.3