%----------------------------------------------------------------------------
\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}