Subversion Repositories shark

%----------------------------------------------------------------------------

\chapter{The Frame Buffer Library}

%----------------------------------------------------------------------------

The S.Ha.R.K. system provides support for all modern SVGA cards through the

Linux Frame Buffer driver. Using the \texttt{grx} graphic library upon it is

possible to draw points, lines, rectangles, boxes, circles, and text on 16 bit

per plane (bpp) SVGA graphic modes.

In order to use graphics, a program must include the

\texttt{drivers/shark\_fb26.h} header file. Then, it must initialize the Frame

Buffer using \texttt{FB26\_init()}. At this point the drawing library must be

connected to the frame buffer with the function \texttt{FB26\_use\_grx()}. Now a

graphic mode can be opened using \texttt{FB26\_setmode()}, and then the drawing

functions can be used. The \emph{num number}, needed as a parameter indicate

which frame buffer is used. At the end, the program can switch back to text mode

through \texttt{FB26\_close()}.

\vspace{7mm}

\begin{intest}

FB26\_INIT \index{FB26\_init()}

\end{intest}

\begin{description}

\item [\textbf{int FB26\_init(void);}]

\item [\textbf{Description:}] It initializes the rame buffer and internal data structures

to access the hardware. The function returns -1 on error, 0 otherwise. In order

to use the graphic primitives, a program must call this function.

\end{description}

\begin{intest}

FB26\_OPEN\index{fb26\_open()}

\end{intest}

\begin{description}

\item [\textbf{int FB26\_open(int num);}]

\item [\textbf{Description:}] Open the frame buffer number \texttt{num}. The function

returns -1 on error, 0 otherwise. The frame buffer must be already initialized

with \texttt{FB26\_init}.

\end{description}

\begin{intest}

FB26\_SETMODE\index{FB26\_setmode()}

\end{intest}

\begin{description}

\item [\textbf{int grx\_setmode(int num, unsigned chat *mode);}]

\item [\textbf{Description:}] It opens the graphic mode identified by the \texttt{mode}

parameter. The mode number can be obtained using \texttt{grx\_getmode()}. The

parameter \texttt{mode} is a string in the format

``\texttt{widthxheight-bpp}'' (ex. ``\texttt{640x480-16}''). If the mode is

supported and can be opened, the function returns 1, otherwise it returns -1.

\end{description}

\begin{intest}

FB26\_CLOSE\index{FB26\_close()}

\end{intest}

\begin{description}

\item [\textbf{int FB26\_close(int num);}]

\item [\textbf{Description:}] It closes the frame buffer \texttt{num} returning to text

mode.

\end{description}

%----------------------------------------------------------------------------

\section{The Frame Buffer graphics functions}

%----------------------------------------------------------------------------

The GRX library allows to use graphics with 16 bpp; the number of bits per

pixel, the graphic depth, determines the number of colors that can be

simultaneously displayed on a single screen. In 16 bpp modes, each pixel is

represented by two bytes. Since 16 is not divisible by 3, a component (the green

one) is described by 6 bits, whereas the other two are described by 5 bits. The

\texttt{RGB16()} macros help to code RGB values in a pixel value for all these

graph functions.

\vspace{7mm}

\begin{intest}

RGB16\index{rgb16()}

\end{intest}

\begin{description}

\item [\textbf{WORD rgb16(WORD r, WORD g, WORD b);}]

\item [\textbf{Description:}] It returns the color value defined by the 3 parameters

(\texttt{red}, \texttt{green} and \texttt{blue}) in the format required by

drawing function.

\end{description}

\begin{intest}

GRX\_CLEAR\index{grx\_clear()}

\end{intest}

\begin{description}

\item [\textbf{void grx\_clear(DWORD color);}]

\item [\textbf{Description:}] It clears the graphic screen by filling it with the color

specified in the parameter \texttt{color}.

\end{description}

\begin{intest}

GRX\_PLOT\index{grx\_plot()}

\end{intest}

\begin{description}

\item [\textbf{void grx\_plot(WORD x, WORD y, DWORD col);}]

\item [\textbf{Description:}] It draws a pixel of color \texttt{c} at coordinates

(\texttt{x},\texttt{y}) on the screen. For efficiency reasons no checks are

performed on \texttt{x} and \texttt{y}. Only the \texttt{bpp} less significative

bits of \texttt{col} are used (where \texttt{bpp} is the number of bits per

plane in the current graphic mode).

\end{description}

\begin{intest}

GRX\_GETPIXEL\index{grx\_getpixel()}

\end{intest}

\begin{description}

\item [\textbf{DWORD grx\_getpixel(WORD x, WORD y);}]

\item [\textbf{Description:}] It returns the color of pixel at coordinates

(\texttt{x}, \texttt{y}) on the screen. For efficiency reasons no checks are

performed on \texttt{x} and \texttt{y}. Only the \texttt{bpp} less significative

bits of the returned value are used (where \texttt{bpp} is the number of bits

per plane in the current graphic mode).

\end{description}

\begin{intest}

GRX\_PUTIMAGE\index{grx\_putimage()}

\end{intest}

\begin{description}

\item [\textbf{void grx\_putimage(WORD x1, WORD y1, WORD x2, WORD y2, WORD *img);}]

\item [\textbf{Description:}] It writes a rectangular bitmap from system memory to video

memory. (\texttt{x1}, \texttt{y1}) is the top left corner, while

(\texttt{x2},\texttt{y2}) is the right bottom corner. It fills the specified box

with the data in the buffer pointed by \texttt{*img}. The memory buffer must

contain the pixels in the same representation used in the video memory, starting

at the top left corner, from left to right, and then, line by line, from up to

down, without any gaps and interline spaces.

\item [See also:] \texttt{grx\_getimage()}.

\end{description}

\begin{description}

\item [Example:]

\end{description}

\begin{tt}

\begin{verbatim}

BYTE videobuff[200][200];

...

void *videotask(void *arg) {

    int done = 0;

    ...

    while (!done) {

        done = decodeframe(videobuff, 200, 200);

        grx_put(X, Y, X + 200, Y + 200, videobuff);

        task_endcycle();

    }

}

\end{verbatim}

\end{tt}

\begin{intest}

GRX\_GETIMAGE\index{grx\_getimage()}

\end{intest}

\begin{description}

\item [\textbf{void grx\_getimage(WORD x1, WORD y1, WORD x2, WORD y2, WORD *img);}]

\item [\textbf{Description:}] It reads a rectangular bitmap from video memory to system

memory. (\texttt{x1}, \texttt{y1}) is the top left corner, while

(\texttt{x2},\texttt{y2}) is the right bottom corner. It fills the specified

buffer pointed by \texttt{*img} with the data contained in the selected video

box. The memory buffer must be large enough to contain the box (in general, the

correct buffer dimension is $(y2-y1+1)*(x2-x1+1)*bpp$).

\item [See]\textbf{also}: \texttt{grx\_putimage()}.

\end{description}

\begin{intest}

GRX\_RECT\index{grx\_rect()}

\end{intest}

\begin{description}

\item [\textbf{int grx\_rect(WORD x1, WORD y1, WORD x2, WORD y2, DWORD col);}]

\item [\textbf{Description:}] It draws an empty rectangle with top left corner at

(\texttt{x1},\texttt{y1}) and bottom right corner at (\texttt{x2},\texttt{y2}).

The rectangle is drawn with color \texttt{col}.

\end{description}

\begin{intest}

GRX\_BOX\index{grx\_box()}

\end{intest}

\begin{description}

\item [\textbf{int grx\_box(WORD x1, WORD y1, WORD x2, WORD y2, DWORD col);}]

\item [\textbf{Description:}] It draws a filled rectangle with top left corner at

(\texttt{x1},\texttt{y1}) and bottom right corner at (\texttt{x2},\texttt{y2}).

The box is drawn with color \texttt{col}.

\end{description}

\begin{intest}

GRX\_LINE\index{grx\_line()}

\end{intest}

\begin{description}

\item [\textbf{void grx\_line(WORD x1, WORD y1, WORD x2, WORD y2, DWORD col);}]

\item [\textbf{Description:}] It draws a line from (\texttt{x1}, \texttt{y1}) to

(\texttt{x2},\texttt{y2}) using color \texttt{col}.

\end{description}

\begin{intest}

GRX\_TEXT\index{grx\_text()}

\end{intest}

\begin{description}

\item [\textbf{void grx\_text(char *text, WORD x, WORD y, DWORD fg, DWORD bg);}]

\item [\textbf{Description:}] It writes a 0 terminated text string in graphic mode at

position (\texttt{x},\texttt{y}). The string is pointed by \texttt{text},

\texttt{fg} is the foreground color, and \texttt{bg} is the background color.

\end{description}

\begin{intest}

GRX\_CIRCLE\index{grx\_circle()}

\end{intest}

\begin{description}

\item [\textbf{void grx\_circle(WORD x, WORD y, WORD r, DWORD col);}]

\item [\textbf{Description:}] It draws a circle of radius \texttt{r} and color

\texttt{col}, centered at (\texttt{x}, \texttt{y}).

\end{description}

\begin{intest}

GRX\_DISC\index{grx\_disc()}

\end{intest}

\begin{description}

\item [\textbf{void grx\_disc(WORD x, WORD y, WORD r, DWORD col);}]

\item [\textbf{Description:}] It draws a filled circle of radius \texttt{r} and color

\texttt{col}, centered at (\texttt{x}, \texttt{y}).

\end{description}