fpc/docs/graph.tex

%
%   $Id$
%   This file is part of the FPC documentation.
%   Copyright (C) 1997, by Michael Van Canneyt
%
%   The FPC documentation is free text; you can redistribute it and/or
%   modify it under the terms of the GNU Library General Public License as
%   published by the Free Software Foundation; either version 2 of the
%   License, or (at your option) any later version.
%
%   The FPC Documentation is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
%   Library General Public License for more details.
%
%   You should have received a copy of the GNU Library General Public
%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
%   Boston, MA 02111-1307, USA. 
%
% Documentation for the 'Graph' unit of Free Pascal.
% Michael Van Canneyt, July 1997
\chapter{The GRAPH unit.}
\FPCexampledir{graphex}
This document describes the \var{GRAPH} unit for Free Pascal, for all
platforms. The unit was first written for \dos by Florian kl\"ampfl, but was
later completely rewritten by Carl-Eric Codere to be completely portable.

This chapter is divided in 4 sections. 
\begin{itemize}
\item The first section gives an introduction to the graph unit.
\item The second section lists the pre-defined constants, types and variables. 
\item The second section describes the functions which appear in the
interface part of the \file{GRAPH} unit.
\item The last part describes some system-specific issues.

\end{itemize}
\section{Introduction}
\label{se:Introduction}
\subsection{Requirements}
The unit Graph exports functions and procedures for graphical output.
It requires at least a VGA-compatible Card or a VGA-Card with software-driver
(min. \textbf{512Kb} video memory).
\subsection{A word about mode selection}
The graph unit was implemented for compatibility with the old \tp graph
unit. For this reason, the mode constants as they were defined in the
\tp graph unit are retained. 

However, since
\begin{enumerate}
\item Video cards have evolved very much
\item Free Pascal runs on multiple platforms
\end{enumerate}
it was decided to implement new mode and graphic driver constants, 
which are more independent of the specific platform the program runs on.

In this section we give a short explanation of the new mode system. the
following drivers were defined:
\begin{verbatim}
D1bit = 11;
D2bit = 12;
D4bit = 13;
D6bit = 14;  { 64 colors Half-brite mode - Amiga }
D8bit = 15;
D12bit = 16; { 4096 color modes HAM mode - Amiga }
D15bit = 17;
D16bit = 18;
D24bit = 19; { not yet supported }
D32bit = 20; { not yet supported }
D64bit = 21; { not yet supported }

lowNewDriver = 11;
highNewDriver = 21;
\end{verbatim}
Each of these drivers specifies a desired color-depth. 

The following modes have been defined:
\begin{verbatim}
detectMode = 30000;
m320x200 = 30001;  
m320x256 = 30002; { amiga resolution (PAL) }
m320x400 = 30003; { amiga/atari resolution }
m512x384 = 30004; { mac resolution }
m640x200 = 30005; { vga resolution }
m640x256 = 30006; { amiga resolution (PAL) }
m640x350 = 30007; { vga resolution }
m640x400 = 30008;
m640x480 = 30009;
m800x600 = 30010;
m832x624 = 30011; { mac resolution }
m1024x768 = 30012;
m1280x1024 = 30013;
m1600x1200 = 30014;
m2048x1536 = 30015;

lowNewMode = 30001;
highNewMode = 30015;
\end{verbatim}
These modes start at 30000 because Borland specified that the mode number
should be ascending with increasing X resolution, and the new constants 
shouldn't interfere with the old ones.

The above constants can be used to set a certain color depth and resultion,
as demonstrated in the following example:

\FPCexample{inigraph1}

If other modes than the ones above are supported by the graphics card,
you will not be able to select them with this mechanism.

For this reason, there is also a 'dynamic' mode number, which is assigned at
run-time. This number increases with increasing X resolution. It can be
queried with the \var{getmoderange} call. This call will return the range
of modes which are valid for a certain graphics driver. The numbers are
guaranteed to be consecutive, and can be used to search for a certain 
resolution, as in the following example:

\FPCexample{inigraph2}


Thus, the \var{getmoderange} function can be used to detect all available 
modes and drivers, as in the following example:

\FPCexample{modrange}

\section{Constants, Types and Variables}
\subsection{Types}
\begin{verbatim}
ArcCoordsType = record
 X,Y,Xstart,Ystart,Xend,Yend : Integer;
end;
FillPatternType = Array [1..8] of Byte;
FillSettingsType = Record
 Pattern,Color : Word
end;
LineSettingsType = Record
  LineStyle,Pattern, Width : Word;
end;
PaletteType = Record
 Size : Byte;
 Colors : array[0..MAxColor] of shortint;
end;
PointType = Record
  X,Y : Integer;
end;
TextSettingsType = Record
 Font,Direction, CharSize, Horiz, Vert : Word
end;
ViewPortType = Record
  X1,Y1,X2,Y2 : Integer;
  Clip : Boolean
end;
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Functions and procedures by category
\section{Function list by category}
What follows is a listing of the available functions, grouped by category.
For each function there is a reference to the page where you can find the
function.
\subsection{Initialization}
Initialization of the graphics screen.
\begin{funclist}
\procref{ClearDevice}{Empty the graphics screen}
\procref{CloseGraph}{Finish drawing session, return to text mode}
\procref{DetectGraph}{Detect graphical modes}
\procref{GetAspectRatio}{Get aspect ratio of screen}
\procref{GetModeRange}{Get range of valid modes for current driver}
\procref{GraphDefaults}{Set defaults}
\funcref{GetDriverName}{Return name of graphical driver}
\funcref{GetGraphMode}{Return current or last used graphics mode}
\funcref{GetMaxMode}{Get maximum mode for current driver}
\funcref{GetModeName}{Get name of current mode}
\funcref{GraphErrorMsg}{String representation of graphical error}
\funcref{GraphResult}{Result of last drawing operation}
\procref{InitGraph}{Initialize graphics drivers}
\funcref{InstallUserDriver}{Install a new driver}
\funcref{RegisterBGIDriver}{Register a new driver}
\procref{RestoreCRTMode}{Go back to text mode}
\procref{SetGraphBufSize}{Set buffer size for graphical operations}
\procref{SetGraphMode}{Set graphical mode}
\end{funclist}

\subsection{screen management}
General drawing screen management functions.
\begin{funclist}
\procref{ClearViewPort}{Clear the current viewport}
\procref{GetImage}{Copy image from screen to memory}
\funcref{GetMaxX}{Get maximum X coordinate}
\funcref{GetMaxY}{Get maximum Y coordinate}
\funcref{GetX}{Get current X position}
\funcref{GetY}{Get current Y position}
\funcref{ImageSize}{Get size of selected image}
\procref{GetViewSettings}{Get current viewport settings}
\procref{PutImage}{Copy image from memory to screen}
\procref{SetActivePage}{Set active video page}
\procref{SetAspectRatio}{Set aspect ratio for drawing routines}
\procref{SetViewPort}{Set current viewport}
\procref{SetVisualPage}{Set visual page}
\procref{SetWriteMode}{Set write mode for screen operations}
\end{funclist}

\subsection{Color management}
All functions related to color management.
\begin{funclist}
\funcref{GetBkColor}{Get current background color}
\funcref{GetColor}{Get current foreground color}
\procref{GetDefaultPalette}{Get default palette entries}
\funcref{GetMaxColor}{Get maximum valid color}
\funcref{GetPaletteSize}{Get size of palette for current mode}
\funcref{GetPixel}{Get color of selected pixel}
\procref{GetPalette}{Get palette entry}
\procref{SetAllPallette}{Set all colors in palette}
\procref{SetBkColor}{Set background color}
\procref{SetColor}{Set foreground color}
\procref{SetPalette}{Set palette entry}
\procref{SetRGBPalette}{Set palette entry with RGB values}
\end{funclist}

\subsection{Drawing primitives}
Functions for simple drawing.
\begin{funclist}
\procref{Arc}{Draw an arc}
\procref{Circle}{Draw a complete circle}
\procref{DrawPoly}{Draw a polygone with N points}
\procref{Ellipse}{Draw an ellipse}
\procref{GetArcCoords}{Get arc coordinates}
\procref{GetLineSettings}{Get current line drawing settings}
\procref{Line}{Draw line between 2 points}
\procref{LineRel}{Draw line relative to current position}
\procref{LineTo}{Draw line from current position to absolute position}
\procref{MoveRel}{Move cursor relative to current position}
\procref{MoveTo}{Move cursor to absolute position}
\procref{PieSlice}{Draw a pie slice}
\procref{PutPixel}{Draw 1 pixel}
\procref{Rectangle}{Draw a non-filled rectangle}
\procref{Sector}{Draw a sector}
\procref{SetLineStyle}{Set current line drawing style}
\end{funclist}

\subsection{Filled drawings}
Functions for drawing filled regions.
\begin{funclist}
\procref{Bar3D}{Draw a filled 3D-style bar}
\procref{Bar}{Draw a filled rectangle}
\procref{FloodFill}{Fill starting from coordinate}
\procref{FillEllipse}{Draw a filled ellipse}
\procref{FillPoly}{Draw a filled polygone}
\procref{GetFillPattern}{Get current fill pattern}
\procref{GetFillSettings}{Get current fill settings}
\procref{SetFillPattern}{Set current fill pattern}
\procref{SetFillStyle}{Set current fill settings}
\end{funclist}

\subsection{Text and font handling}
Functions to set texts on the screen.
\begin{funclist}
\procref{GetTextSettings}{Get current text settings}
\funcref{InstallUserFont}{Install a new font}
\procref{OutText}{Write text at current cursor position}
\procref{OutTextXY}{Write text at coordinates X,Y}
\funcref{RegisterBGIFont}{Register a new font}
\procref{SetTextJustify}{Set text justification}
\procref{SetTextStyle}{Set text style}
\procref{SetUserCharSize}{Set text size}
\funcref{TextHeight}{Calculate height of text}
\funcref{TextWidth}{Calculate width of text}
\end{funclist}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Functions and procedures
\section{Functions and procedures}

\begin{procedure}{Arc}
\Declaration
Procedure Arc (X,Y : Integer; start,stop, radius : Word);

\Description
 \var{Arc} draws part of a circle with center at \var{(X,Y)}, radius
\var{radius}, starting from angle \var{start}, stopping at angle \var{stop}.
These  angles are measured
counterclockwise.
\Errors
None.
\SeeAlso
\seep{Circle},\seep{Ellipse} 
\seep{GetArcCoords},\seep{PieSlice}, \seep{Sector}
\end{procedure}

\begin{procedure}{Bar}
\Declaration
Procedure Bar (X1,Y1,X2,Y2 : Integer);

\Description
Draws a rectangle with corners at \var{(X1,Y1)} and \var{(X2,Y2)} 
and fills it with the current color and fill-style.
\Errors
None.
\SeeAlso
\seep{Bar3D}, 
\seep{Rectangle}
\end{procedure}

\begin{procedure}{Bar3D}
\Declaration
Procedure Bar3D (X1,Y1,X2,Y2 : Integer; depth : Word; Top : Boolean);

\Description
Draws a 3-dimensional Bar  with corners at \var{(X1,Y1)} and \var{(X2,Y2)} 
and fills it with the current color and fill-style.
\var{Depth} specifies the number of pixels used to show the depth of the
bar.
If \var{Top} is true; then a 3-dimensional top is drawn.
\Errors
None.
\SeeAlso
\seep{Bar}, \seep{Rectangle}
\end{procedure}

\begin{procedure}{Circle}
\Declaration
Procedure Circle (X,Y : Integer; Radius : Word);

\Description
 \var{Circle} draws part of a circle with center at \var{(X,Y)}, radius
\var{radius}.
\Errors
None.
\SeeAlso
\seep{Ellipse},\seep{Arc}
\seep{GetArcCoords},\seep{PieSlice}, \seep{Sector}
\end{procedure}

\begin{procedure}{ClearDevice}
\Declaration
Procedure ClearDevice ;

\Description
Clears the graphical screen (with the current
background color), and sets the pointer at \var{(0,0)}
\Errors
None.
\SeeAlso
\seep{ClearViewPort}, \seep{SetBkColor}
\end{procedure}

\begin{procedure}{ClearViewPort}
\Declaration
Procedure ClearViewPort ;

\Description
Clears the current viewport. The current background color is used as filling
color. The pointer is set at
\var{(0,0)}
\Errors
None.
\SeeAlso
\seep{ClearDevice},\seep{SetViewPort}, \seep{SetBkColor}
\end{procedure}

\begin{procedure}{CloseGraph}
\Declaration
Procedure CloseGraph ;

\Description
Closes the graphical system, and restores the
screen modus which was active before the graphical modus was
activated.
\Errors
None.
\SeeAlso
\seep{InitGraph}
\end{procedure}

\begin{procedure}{DetectGraph}
\Declaration
Procedure DetectGraph (Var Driver, Modus : Integer);

\Description
 Checks the hardware in the PC and determines the driver and screen-modus to
be used. These are returned in \var{Driver} and \var{Modus}, and can be fed
to \var{InitGraph}. 
See the \var{InitGraph} for a list of drivers and modi.
\Errors
None.
\SeeAlso
\seep{InitGraph}
\end{procedure}

\begin{procedure}{DrawPoly}
\Declaration
Procedure DrawPoly (NumberOfPoints : Word; Var PolyPoints;

\Description

Draws a polygone with \var{NumberOfPoints} corner points, using the
current color and line-style. PolyPoints is an array of type \var{PointType}.

\Errors
None.
\SeeAlso
\seep{Bar}, seep{Bar3D}, \seep{Rectangle}
\end{procedure}

\begin{procedure}{Ellipse}
\Declaration
Procedure Ellipse (X,Y : Integer; Start,Stop,XRadius,YRadius : Word);

\Description
 \var{Ellipse} draws part of an ellipse with center at \var{(X,Y)}.
\var{XRadius} and \var{Yradius} are the horizontal and vertical radii of the
ellipse. \var{Start} and \var{Stop} are the starting and stopping angles of
the part of the ellipse. They are measured counterclockwise from the X-axis 
(3 o'clock is equal to 0 degrees). Only positive angles can be specified.
\Errors
None.
\SeeAlso
\seep{Arc} \seep{Circle}, \seep{FillEllipse}
\end{procedure}

\begin{procedure}{FillEllipse}
\Declaration
Procedure FillEllipse (X,Y : Integer; Xradius,YRadius: Word);

\Description
 \var{Ellipse} draws an ellipse with center at \var{(X,Y)}.
\var{XRadius} and \var{Yradius} are the horizontal and vertical radii of the
ellipse. The ellipse is filled with the current color and fill-style.
\Errors
None.
\SeeAlso
\seep{Arc} \seep{Circle},
\seep{GetArcCoords},\seep{PieSlice}, \seep{Sector}
\end{procedure}

\begin{procedure}{FillPoly}
\Declaration
Procedure FillPoly (NumberOfPoints : Word; Var PolyPoints);

\Description

Draws a polygone with \var{NumberOfPoints} corner points and fills it
using the current color and line-style. 
PolyPoints is an array of type \var{PointType}.

\Errors
None.
\SeeAlso
\seep{Bar}, seep{Bar3D}, \seep{Rectangle}
\end{procedure}

\begin{procedure}{FloodFill}
\Declaration
Procedure FloodFill (X,Y : Integer; BorderColor : Word);

\Description

Fills the area containing the point \var{(X,Y)}, bounded by the color
\var{BorderColor}.
\Errors
None
\SeeAlso
\seep{SetColor}, \seep{SetBkColor}
\end{procedure}

\begin{procedure}{GetArcCoords}
\Declaration
Procedure GetArcCoords (Var ArcCoords : ArcCoordsType);

\Description
\var{GetArcCoords} returns the coordinates of the latest \var{Arc} or
\var{Ellipse} call.
\Errors
None.
\SeeAlso
\seep{Arc}, \seep{Ellipse}
\end{procedure}

\begin{procedure}{GetAspectRatio}
\Declaration
Procedure GetAspectRatio (Var Xasp,Yasp : Word);

\Description
\var{GetAspectRatio} determines the effective resolution of the screen. The aspect ration can
the be calculated as \var{Xasp/Yasp}.
\Errors
None.
\SeeAlso
\seep{InitGraph},\seep{SetAspectRatio}
\end{procedure}

\begin{function}{GetBkColor}
\Declaration
Function GetBkColor  : Word;

\Description
\var{GetBkColor} returns the current background color (the palette
entry).
\Errors
None.
\SeeAlso
\seef{GetColor},\seep{SetBkColor}
\end{function}

\begin{function}{GetColor}
\Declaration
Function GetColor  : Word;

\Description
\var{GetColor} returns the current drawing color (the palette
entry).
\Errors
None.
\SeeAlso
\seef{GetColor},\seep{SetBkColor}
\end{function}

\begin{procedure}{GetDefaultPalette}
\Declaration
Procedure GetDefaultPalette (Var Palette : PaletteType);

\Description
Returns the
current palette in \var{Palette}.
\Errors
None.
\SeeAlso
\seef{GetColor}, \seef{GetBkColor}
\end{procedure}

\begin{function}{GetDriverName}
\Declaration
Function GetDriverName  : String;

\Description
\var{GetDriverName} returns a string containing the name of the
current driver.
\Errors
None.
\SeeAlso
\seef{GetModeName}, \seep{InitGraph}
\end{function}

\begin{procedure}{GetFillPattern}
\Declaration
Procedure GetFillPattern (Var FillPattern : FillPatternType);

\Description
\var{GetFillPattern} returns an array with the current fill-pattern  in \var{FillPattern}
\Errors
None
\SeeAlso
\seep{SetFillPattern}
\end{procedure}

\begin{procedure}{GetFillSettings}
\Declaration
Procedure GetFillSettings (Var FillInfo : FillSettingsType);

\Description
\var{GetFillSettings} returns the current fill-settings in
\var{FillInfo}
\Errors
None.
\SeeAlso
\seep{SetFillPattern}
\end{procedure}

\begin{function}{GetGraphMode}
\Declaration
Function GetGraphMode  : Integer;

\Description
\var{GetGraphMode} returns the current graphical modus
\Errors
None.
\SeeAlso
\seep{InitGraph}
\end{function}

\begin{procedure}{GetImage}
\Declaration
Procedure GetImage (X1,Y1,X2,Y2 : Integer, Var Bitmap;

\Description
\var{GetImage}
Places a copy of the screen area \var{(X1,Y1)} to \var{X2,Y2} in \var{BitMap}
\Errors
Bitmap must have enough room to contain the image.
\SeeAlso
\seef{ImageSize},
\seep{PutImage}
\end{procedure}

\begin{procedure}{GetLineSettings}
\Declaration
Procedure GetLineSettings (Var LineInfo : LineSettingsType);

\Description
\var{GetLineSettings} returns the current Line settings in
\var{LineInfo}
\Errors
None.
\SeeAlso
\seep{SetLineStyle}
\end{procedure}

\begin{function}{GetMaxColor}
\Declaration
Function GetMaxColor  : Word;

\Description
\var{GetMaxColor} returns the maximum color-number which can be 
set with \var{SetColor}. Contrary to \tp, this color isn't always 
guaranteed to be white (for instance in 256+ color modes).
\Errors
None.
\SeeAlso
\seep{SetColor},
\seef{GetPaletteSize}
\end{function}

\begin{function}{GetMaxMode}
\Declaration
Function GetMaxMode  : Word;

\Description
\var{GetMaxMode} returns the highest modus for
the current driver.
\Errors
None.
\SeeAlso
\seep{InitGraph}
\end{function}

\begin{function}{GetMaxX}
\Declaration
Function GetMaxX  : Word;

\Description
\var{GetMaxX} returns the maximum horizontal screen
length
\Errors
None.
\SeeAlso
\seef{GetMaxY}
\end{function}

\begin{function}{GetMaxY}
\Declaration
Function GetMaxY  : Word;

\Description
\var{GetMaxY} returns the maximum number of screen
lines
\Errors
None.
\SeeAlso
\seef{GetMaxY}
\end{function}

\begin{function}{GetModeName}
\Declaration
Function GetModeName (Var modus : Integer) : String;

\Description

Returns a string with the name of modus
\var{Modus}
\Errors
None.
\SeeAlso
\seef{GetDriverName}, \seep{InitGraph}
\end{function}

\begin{procedure}{GetModeRange}
\Declaration
Procedure GetModeRange (Driver : Integer; \\ LoModus, HiModus: Integer);
\Description
\var{GetModeRange} returns the Lowest and Highest modus of the currently
installed driver. If no modes are supported for this driver, HiModus
will be -1.
\Errors
None.
\SeeAlso
\seep{InitGraph}
\end{procedure}

\begin{procedure}{GetPalette}
\Declaration
Procedure GetPalette (Var Palette : PaletteType);

\Description
\var{GetPalette} returns in \var{Palette} the current palette.
\Errors
None.
\SeeAlso
\seef{GetPaletteSize}, \seep{SetPalette}
\end{procedure}

\begin{function}{GetPaletteSize}
\Declaration
Function GetPaletteSize  : Word;

\Description
\var{GetPaletteSize} returns the maximum
number of entries in the current palette.
\Errors
None.
\SeeAlso
\seep{GetPalette},
\seep{SetPalette}
\end{function}

\begin{function}{GetPixel}
\Declaration
Function GetPixel (X,Y : Integer) : Word;

\Description
\var{GetPixel} returns the color
of the point at \var{(X,Y)} 
\Errors
None.
\SeeAlso

\end{function}

\begin{procedure}{GetTextSettings}
\Declaration
Procedure GetTextSettings (Var TextInfo : TextSettingsType);

\Description
\var{GetTextSettings} returns the current text style settings : The font,
direction, size and placement as set with \var{SetTextStyle} and
\var{SetTextJustify}
\Errors
None.
\SeeAlso
\seep{SetTextStyle}, \seep{SetTextJustify}
\end{procedure}

\begin{procedure}{GetViewSettings}
\Declaration
Procedure GetViewSettings (Var ViewPort : ViewPortType);

\Description
\var{GetViewSettings} returns the current viewport and clipping settings in
\var{ViewPort}.
\Errors
None.
\SeeAlso
\seep{SetViewPort}
\end{procedure}

\begin{function}{GetX}
\Declaration
Function GetX  : Integer;

\Description
\var{GetX} returns the X-coordinate of the current position of
the graphical pointer
\Errors
None.
\SeeAlso
\seef{GetY}
\end{function}

\begin{function}{GetY}
\Declaration
Function GetY  : Integer;

\Description
\var{GetY} returns the Y-coordinate of the current position of
the graphical pointer
\Errors
None.
\SeeAlso
\seef{GetX}
\end{function}

\begin{procedure}{GraphDefaults}
\Declaration
Procedure GraphDefaults ;

\Description
\var{GraphDefaults} resets all settings for viewport, palette,
foreground and background pattern, line-style and pattern, filling style,
filling color and pattern, font, text-placement and
text size.
\Errors
None.
\SeeAlso
\seep{SetViewPort}, \seep{SetFillStyle}, \seep{SetColor},
\seep{SetBkColor}, \seep{SetLineStyle}
\end{procedure}

\begin{function}{GraphErrorMsg}
\Declaration
Function GraphErrorMsg (ErrorCode : Integer) : String;

\Description
\var{GraphErrorMsg}
returns a string describing the error \var{Errorcode}. This string can be
used to let the user know what went wrong.
\Errors
None.
\SeeAlso
\seef{GraphResult}
\end{function}

\begin{function}{GraphResult}
\Declaration
Function GraphResult  : Integer;

\Description
\var{GraphResult} returns an error-code for
the last graphical operation. If the returned value is zero, all went well.
A value different from zero means an error has occurred.
besides all operations which draw something on the screen, 
the following procedures also can produce a \var{GraphResult} different from
zero:

\begin{itemize}
\item \seef{InstallUserFont}
\item \seep{SetLineStyle}
\item \seep{SetWriteMode}
\item \seep{SetFillStyle}
\item \seep{SetTextJustify}
\item \seep{SetGraphMode}
\item \seep{SetTextStyle}
\end{itemize}

\Errors
None.
\SeeAlso
\seef{GraphErrorMsg}
\end{function}

\begin{function}{ImageSize}
\Declaration
Function ImageSize (X1,Y1,X2,Y2 : Integer) : Word;

\Description
\var{ImageSize} returns
the number of bytes needed to store the image in the rectangle defined by
\var{(X1,Y1)} and \var{(X2,Y2)}.
\Errors
None.
\SeeAlso
\seep{GetImage}
\end{function}

\begin{procedure}{InitGraph}
\Declaration
Procedure InitGraph (var GraphDriver,GraphModus : integer;\\
const PathToDriver : string);

\Description

\var{InitGraph} initializes the \var{graph} package.
\var{GraphDriver} has two valid values: \var{GraphDriver=0} which
performs an auto detect and initializes the highest possible mode with the most
colors. 1024x768x64K is the highest possible resolution supported by the
driver, if you need a higher resolution, you must edit \file{MODES.PPI}. 
If you need another mode, then set \var{GraphDriver} to a value different
from zero
and \var{graphmode} to the mode you wish (VESA modes where 640x480x256
is \var {101h} etc.).
\var{PathToDriver} is only needed, if you use the BGI fonts from
Borland.
\Errors
None.
\SeeAlso
Introduction, (page \pageref{se:Introduction}),
\seep{DetectGraph}, \seep{CloseGraph}, \seef{GraphResult}
\end{procedure}
Example:

\begin{verbatim}
var 
   gd,gm : integer; 
   PathToDriver : string; 
begin 
   gd:=detect; { highest possible resolution } 
   gm:=0; { not needed, auto detection } 
   PathToDriver:='C:\PP\BGI'; { path to BGI fonts, 
                                drivers aren't needed } 
   InitGraph(gd,gm,PathToDriver); 
   if GraphResult<>grok then 
     halt; ..... { whatever you need } 
   CloseGraph; { restores the old graphics mode } 
end.
\end{verbatim}

\begin{function}{InstallUserDriver}
\Declaration
Function InstallUserDriver (DriverPath : String; \\AutoDetectPtr: Pointer) : Integer;

\Description
\var{InstallUserDriver} 
adds the device-driver \var{DriverPath} to the list of .BGI
drivers. \var{AutoDetectPtr} is a pointer to a possible auto-detect function.
\Errors
None.
\SeeAlso
\seep{InitGraph}, \seef{InstallUserFont}
\end{function}

\begin{function}{InstallUserFont}
\Declaration
Function InstallUserFont (FontPath : String) : Integer;

\Description
\var{InstallUserFont} adds the font in \var{FontPath} to the list of fonts
of the .BGI system.
\Errors
None.
\SeeAlso
\seep{InitGraph}, \seef{InstallUserDriver}
\end{function}

\begin{procedure}{Line}
\Declaration
Procedure Line (X1,Y1,X2,Y2 : Integer);

\Description
\var{Line} draws a line starting from
\var{(X1,Y1} to \var{(X2,Y2)}, in the current line style and color. The
current position is put to \var{(X2,Y2)}
\Errors
None.
\SeeAlso
\seep{LineRel},\seep{LineTo}
\end{procedure}

\begin{procedure}{LineRel}
\Declaration
Procedure LineRel (DX,DY : Integer);

\Description
\var{LineRel} draws a line starting from
the current pointer position to the point\var{(DX,DY}, \textbf{relative} to the
current position, in the current line style and color. The Current Position
is set to the endpoint of the line.
\Errors
None.
\SeeAlso
\seep{Line}, \seep{LineTo}
\end{procedure}

\begin{procedure}{LineTo}
\Declaration
Procedure LineTo (DX,DY : Integer);

\Description
\var{LineTo} draws a line starting from
the current pointer position to the point\var{(DX,DY}, \textbf{relative} to the
current position, in the current line style and color. The Current position
is set to the end of the line.
\Errors
None.
\SeeAlso
\seep{LineRel},\seep{Line}
\end{procedure}

\begin{procedure}{MoveRel}
\Declaration
Procedure MoveRel (DX,DY : Integer;

\Description
\var{MoveRel} moves the pointer to the
point \var{(DX,DY)}, relative to the current pointer
position
\Errors
None.
\SeeAlso
\seep{MoveTo}
\end{procedure}

\begin{procedure}{MoveTo}
\Declaration
Procedure MoveTo (X,Y : Integer;

\Description
\var{MoveTo} moves the pointer to the
point \var{(X,Y)}.
\Errors
None.
\SeeAlso
\seep{MoveRel}
\end{procedure}

\begin{procedure}{OutText}
\Declaration
Procedure OutText (Const TextString : String);

\Description
\var{OutText} puts \var{TextString} on the screen, at the current pointer
position, using the current font and text settings. The current position is
moved to the end of the text.
\Errors
None.
\SeeAlso
\seep{OutTextXY}
\end{procedure}

\begin{procedure}{OutTextXY}
\Declaration
Procedure OutTextXY (X,Y : Integer; Const TextString : String);

\Description
\var{OutText} puts \var{TextString} on the screen, at position \var{(X,Y)},
using the current font and text settings. The current position is
moved to the end of the text.
\Errors
None.
\SeeAlso
\seep{OutText}
\end{procedure}

\begin{procedure}{PieSlice}
\Declaration
Procedure PieSlice (X,Y : Integer; \\ Start,Stop,Radius : Word);

\Description
\var{PieSlice}
draws and fills a sector of a circle with center \var{(X,Y)} and radius 
\var{Radius}, starting at angle \var{Start} and ending at angle \var{Stop}.
\Errors
None.
\SeeAlso
\seep{Arc}, \seep{Circle}, \seep{Sector}
\end{procedure}

\begin{procedure}{PutImage}
\Declaration
Procedure PutImage (X1,Y1 : Integer; Var Bitmap; How : word) ;

\Description
\var{PutImage}
Places the bitmap in \var{Bitmap} on the screen at \var{(X1,Y1)}. \var{How}
determines how the bitmap will be placed on the screen. Possible values are :

\begin{itemize}
\item CopyPut
\item XORPut
\item ORPut
\item AndPut
\item NotPut
\end{itemize}
\Errors
None
\SeeAlso
\seef{ImageSize},\seep{GetImage}
\end{procedure}

\begin{procedure}{PutPixel}
\Declaration
Procedure PutPixel (X,Y : Integer; Color : Word);

\Description
Puts a point at
\var{(X,Y)} using color \var{Color}
\Errors
None.
\SeeAlso
\seef{GetPixel}
\end{procedure}

\begin{procedure}{Rectangle}
\Declaration
Procedure Rectangle (X1,Y1,X2,Y2 : Integer);

\Description
Draws a rectangle with
corners at \var{(X1,Y1)} and \var{(X2,Y2)}, using the current color and
style.
\Errors
None.
\SeeAlso
\seep{Bar}, \seep{Bar3D}
\end{procedure}

\begin{function}{RegisterBGIDriver}
\Declaration
Function RegisterBGIDriver (Driver : Pointer) : Integer;

\Description
Registers a user-defined BGI driver
\Errors
None.
\SeeAlso
\seef{InstallUserDriver},
\seef{RegisterBGIFont}
\end{function}

\begin{function}{RegisterBGIFont}
\Declaration
Function RegisterBGIFont (Font : Pointer) : Integer;

\Description
Registers a user-defined BGI driver
\Errors
None.
\SeeAlso
\seef{InstallUserFont},
\seef{RegisterBGIDriver}
\end{function}

\begin{procedure}{RestoreCRTMode}
\Declaration
Procedure RestoreCRTMode ;

\Description
Restores the screen modus which was active before
the graphical modus was started.

To get back to the graph mode you were last in, you can use
\var{SetGraphMode(GetGraphMode)}
\Errors
None.
\SeeAlso
\seep{InitGraph}
\end{procedure}

\begin{procedure}{Sector}
\Declaration
Procedure Sector (X,Y : Integer; \\ Start,Stop,XRadius,YRadius : Word);

\Description
\var{Sector}
draws and fills a sector of an ellipse  with center \var{(X,Y)} and radii 
\var{XRadius} and \var{YRadius}, starting at angle \var{Start} and ending at angle \var{Stop}.
\Errors
None.
\SeeAlso
\seep{Arc}, \seep{Circle}, \seep{PieSlice}
\end{procedure}

\begin{procedure}{SetActivePage}
\Declaration
Procedure SetActivePage (Page : Word);

\Description
Sets \var{Page} as the active page 
for all graphical output.
\Errors
None.
\SeeAlso

\end{procedure}

\begin{procedure}{SetAllPallette}
\Declaration
Procedure SetAllPallette (Var Palette);

\Description
Sets the current palette to
\var{Palette}. \var{Palette} is an untyped variable, usually pointing to a
record of type \var{PaletteType}
\Errors
None.
\SeeAlso
\seep{GetPalette}
\end{procedure}

\begin{procedure}{SetAspectRatio}
\Declaration
Procedure SetAspectRatio (Xasp,Yasp : Word);

\Description
Sets the aspect ratio of the
current screen to \var{Xasp/Yasp}.
\Errors
None
\SeeAlso
\seep{InitGraph}, \seep{GetAspectRatio}
\end{procedure}

\begin{procedure}{SetBkColor}
\Declaration
Procedure SetBkColor (Color : Word);

\Description
Sets the background color to
\var{Color}.
\Errors
None.
\SeeAlso
\seef{GetBkColor}, \seep{SetColor}
\end{procedure}

\begin{procedure}{SetColor}
\Declaration
Procedure SetColor (Color : Word);

\Description
Sets the foreground color to
\var{Color}.
\Errors
None.
\SeeAlso
\seef{GetColor}, \seep{SetBkColor}
\end{procedure}

\begin{procedure}{SetFillPattern}
\Declaration
Procedure SetFillPattern (FillPattern : FillPatternType,\\ Color : Word);

\Description
\var{SetFillPattern} sets the current fill-pattern to \var{FillPattern}, and
the filling color to \var{Color}
The pattern is an 8x8 raster, corresponding to the 64 bits in
\var{FillPattern}.
\Errors
None
\SeeAlso
\seep{GetFillPattern}, \seep{SetFillStyle}
\end{procedure}

\begin{procedure}{SetFillStyle}
\Declaration
Procedure SetFillStyle (Pattern,Color : word);

\Description
\var{SetFillStyle} sets the filling pattern and color to one of the
predefined filling patterns. \var{Pattern} can be one of the following predefined
constants :

\begin{itemize}
\item \var{EmptyFill  } Uses backgroundcolor.
\item \var{SolidFill  } Uses filling color
\item \var{LineFill   } Fills with horizontal lines.
\item \var{ltSlashFill} Fills with lines from left-under to top-right.
\item \var{SlashFill  } Idem as previous, thick lines.
\item \var{BkSlashFill} Fills with thick lines from left-Top to bottom-right.
\item \var{LtBkSlashFill} Idem as previous, normal lines.
\item \var{HatchFill}  Fills with a hatch-like pattern.
\item \var{XHatchFill} Fills with a hatch pattern, rotated 45 degrees.
\item \var{InterLeaveFill} 
\item \var{WideDotFill} Fills with dots, wide spacing.
\item \var{CloseDotFill} Fills with dots, narrow spacing.
\item \var{UserFill} Fills with a user-defined pattern.
\end{itemize}

\Errors
None.
\SeeAlso
\seep{SetFillPattern}
\end{procedure}

\begin{procedure}{SetGraphBufSize}
\Declaration
Procedure SetGraphBufSize (BufSize : Word);

\Description
\var{SetGraphBufSize} is a dummy function which does not do 
anything; it is no longer needed.
\Errors
None.
\SeeAlso

\end{procedure}

\begin{procedure}{SetGraphMode}
\Declaration
Procedure SetGraphMode (Mode : Integer);

\Description
\var{SetGraphMode} sets the graphical mode and clears the screen.
\Errors
None.
\SeeAlso
\seep{InitGraph}
\end{procedure}

\begin{procedure}{SetLineStyle}
\Declaration
Procedure SetLineStyle (LineStyle,Pattern,Width :
Word);

\Description
\var{SetLineStyle}
sets the drawing style for lines. You can specify a \var{LineStyle} which is
one of the following pre-defined constants:

\begin{itemize}
\item \var{Solidln=0;} draws a solid line.
\item \var{Dottedln=1;} Draws a dotted line.
\item \var{Centerln=2;} draws a non-broken centered line.
\item \var{Dashedln=3;} draws a dashed line.
\item \var{UserBitln=4;} Draws a User-defined bit pattern.
\end{itemize}
If \var{UserBitln} is specified then \var{Pattern} contains the bit pattern.
In all another cases, \var{Pattern} is ignored. The parameter \var{Width} 
indicates how thick the line should be. You can specify one of the following
pre-defined constants:

\begin{itemize}
\item \var{NormWidth=1}
\item \var{ThickWidth=3}
\end{itemize}

\Errors
None.
\SeeAlso
\seep{GetLineSettings}
\end{procedure}

\begin{procedure}{SetPalette}
\Declaration
Procedure SetPalette (ColorNr : Word; NewColor : ShortInt);

\Description
\var{SetPalette} changes the \var{ColorNr}-th entry in the palette to
\var{NewColor}
\Errors
None.
\SeeAlso
\seep{SetAllPallette},\seep{SetRGBPalette}
\end{procedure}

\begin{procedure}{SetRGBPalette}
\Declaration
Procedure SetRGBPalette (ColorNr,Red,Green,Blue : Integer);

\Description
\var{SetRGBPalette} sets the \var{ColorNr}-th entry in the palette to the
color with RGB-values \var{Red, Green Blue}.
\Errors
None.
\SeeAlso
\seep{SetAllPallette},
\seep{SetPalette}
\end{procedure}

\begin{procedure}{SetTextJustify}
\Declaration
Procedure SetTextJustify (Horizontal,Vertical : Word);

\Description
\var{SetTextJustify} controls the placement of new text, relative to the 
(graphical) cursor position. \var{Horizontal} controls horizontal placement, and can be
one of the following pre-defined constants:

\begin{itemize}
\item \var{LeftText=0;} Text is set left of the pointer.
\item \var{CenterText=1;} Text is set centered horizontally on the pointer.
\item \var{RightText=2;} Text is set to the right of the pointer.
\end{itemize}
\var{Vertical} controls the vertical placement of the text, relative to the
(graphical) cursor position. Its value can be one of the following
pre-defined constants :

\begin{itemize}
\item \var{BottomText=0;} Text is placed under the pointer.
\item \var{CenterText=1;} Text is placed centered vertically on the pointer.
\item \var{TopText=2;}Text is placed above the pointer.
\end{itemize}

\Errors
None.
\SeeAlso
\seep{OutText}, \seep{OutTextXY}
\end{procedure}

\begin{procedure}{SetTextStyle}
\Declaration
Procedure SetTextStyle (Font,Direction,Magnitude : Word);

\Description
\var{SetTextStyle} controls the style of text to be put on the screen.
pre-defined constants for \var{Font} are:

\begin{itemize}
\item \var{DefaultFont=0;}
\item \var{TriplexFont=2;}
\item \var{SmallFont=2;}
\item \var{SansSerifFont=3;}
\item \var{GothicFont=4;}
\end{itemize}
Pre-defined constants for \var{Direction} are :

\begin{itemize}
\item \var{HorizDir=0;}
\item \var{VertDir=1;}
\end{itemize}
\Errors
None.
\SeeAlso
\seep{GetTextSettings} 
\end{procedure}

\begin{procedure}{SetUserCharSize}
\Declaration
Procedure SetUserCharSize (Xasp1,Xasp2,Yasp1,Yasp2 : Word);

\Description
Sets the width and height of vector-fonts. The horizontal size is given
by \var{Xasp1/Xasp2}, and the vertical size by \var{Yasp1/Yasp2}.
\Errors
None.
\SeeAlso
\seep{SetTextStyle}
\end{procedure}

\begin{procedure}{SetViewPort}
\Declaration
Procedure SetViewPort (X1,Y1,X2,Y2 : Integer; Clip : Boolean);

\Description
Sets the current graphical viewport (window) to the rectangle defined by
the top-left corner \var{(X1,Y1)} and the bottom-right corner \var{(X2,Y2)}.
If \var{Clip} is true, anything drawn outside the viewport (window) will be
clipped (i.e. not drawn). Coordinates specified after this call are relative
to the top-left corner of the viewport.
\Errors
None.
\SeeAlso
\seep{GetViewSettings}
\end{procedure}

\begin{procedure}{SetVisualPage}
\Declaration
Procedure SetVisualPage (Page : Word);

\Description
\var{SetVisualPage} sets the video page to page number \var{Page}. 
\Errors
None
\SeeAlso
\seep{SetActivePage}
\end{procedure}

\begin{procedure}{SetWriteMode}
\Declaration
Procedure SetWriteMode (Mode : Integer);

\Description
\var{SetWriteMode} controls the drawing of lines on the screen. It controls
the binary operation used when drawing lines on the screen. \var{Mode} can
be one of the following pre-defined constants:

\begin{itemize}
\item CopyPut=0;
\item XORPut=1;
\end{itemize}
\Errors
None.
\SeeAlso

\end{procedure}

\begin{function}{TextHeight}
\Declaration
Function TextHeight (S : String) : Word;

\Description
\var{TextHeight} returns the height (in pixels) of the string \var{S} in
the current font and text-size.

\Errors
None.
\SeeAlso
\seef{TextWidth}
\end{function}

\begin{function}{TextWidth}
\Declaration
Function TextWidth (S : String) : Word;

\Description
\var{TextHeight} returns the width (in pixels) of the string \var{S} in
the current font and text-size.
\Errors
None.
\SeeAlso
\seef{TextHeight}
\end{function}

% Target specific issues.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Target specific issues}                                                                                                                                                                                                                                                               
In what follows we describe some things that are different on the various
platforms:

\subsection{\dos}
\subsection{\windows}
\subsection{\linux}