Initial revision

[AROS-Contrib.git] / development / compilers / freepascal / rtl / inc / graph / graph.tex

%
%   $Id$
%   This file is part of the FPC documentation.
%   Copyright (C) 1997,1999-2000 by the Free Pascal Development team
%
%   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
% Carl Eric Codere, April 1999
\chapter{The GRAPH unit.}
This document describes the \textbf{GRAPH} unit for Free Pascal. This unit includes
more then 50 graphics routines, that range from low-level calls such as putpixel
to high level calls like Circle and Bar3D. Different fill styles and line
patterns are supported in most of the routines.

\section{Overview}
\label{se:Overview}

\subsection{Compatibility}
Since the graph unit included with \var{fpc} is a portable implementation of
the Turbo Pascal unit, there are some slight differences between the video
modes and features.

\subsubsection{Initialization}

Each graph unit implementation, will have a 320x200 resolution refered to
\textit{LowResolution}. If the hardware for the specific platform does
not support that resolution, then it will have to be emulated. Apart
from that requirement, all other resolutions will be dependant on the
target platform.

The correct way and portable way to initialize to graphics subsystem, is
to first query the hardware, and then from that, decide which mode you
wish to support. The routine which does this is called \textit{QueryAdapterInfo}.
This routine returns a linked list of modes availables, and their
mode number as well as driver numbers. It is to note that this list is
initialized only once during the lifetime of the application (that is,
even if CloseGraph is called, the list will still be valid). The memory
allocated for this list is automatically freed as part as the graph
unit's exit procedure.

You can always use Detect as a parameter to \textit{InitGraph}
which will initialize the graphics to the highest resolution possible.

The following constants are also defined for compatiblity with older
applications written with Turbo Pascal, they should no longer be used:

\begin{tabular}{|c|c|c|}
\hline
 Driver Name & Constant Name & Column x Row & Colors \\ \hline
 VGA & VGAHi & 640x480 & 16 \\
 VGA & VGALo & 640x200 & 16 \\
 VGA & VGAMed & 640x350 & 16 \\
 VGA & VGA256 & 320x200 & 256 \\
\hline
\end{tabular}

\subsubsection{Other differences}

Some notable differences with the Turbo Pascal graph unit are noted
below:

\begin{itemize}
\item \textit{Rectangle} do not write
  the end points twice, which permits the XORPut write mode to be used
  effectively for erasing these forms on the screen.
\item \textit{RegisterBGIDriver} and \textit{InstallUserDriver} always
  return errors, as they are not directly supported.
\item \textit{DrawPoly} XORPut write mode does not have the same behaviour
 as the one in the Turbo Pascal graph unit.
\item XORPut write mode is not supported by \textit{Bar3d}.
\item Passing invalid parameters to \textit{SetTextStyle} will not
  result in the same visual appearance. Make sure your input is valid.
\item All routines using sines/cosines (e.g: \textit{circle}), don't
 exactly have the same radii, because the aspect ratio correction is
 different.
\item PutImage supports clipping.
\item \textit{SetRGBPalette} use the LSB's of the RGB components to
set the color values of the palette. This makes the unit more portable.
\item \textit{PaletteType} is different then the Turbo Pascal version,
  it uses RGB Values for the palettes.
\item \textit{SetAllPalette} is different then the Turbo Pascal version,
  it uses the PaletteType as a parameter.
\item \textit{GetDefaultPalette} only returns only at most the 256 first
  default entries of a palette, even if the mode supports more then
  256 colors.
\end{itemize}

\subsection{Coordinate system}
The upper left of the graphics screen is located at position (0,0). The x
value, which represents the column, increments to the right. The y values,
or rows, increment downward. The maximum value which can be set for an x
value, for the graphics screen is given by the \textit{GetMaxX} routine.
The same is true for the y coordinate, except a call to \textit{GetMaxY}
is required.

\subsection{Current pointer}
Some graphics routines support the concept of the current pointer (CP). The
current pointer is similar in concept to a text cursor, except that it is
invisible.

When you write in text mode, the text cursor is automatically incremented
by the number of characters written. The same is true with the graphics
current pointer, which is instead incremented on a pixel basis.

For example, the following:
\begin{verbatim}

   MoveTo(0,0);
   LineTo(100,100);

\end{verbatim}

will leave the current pointer to the (100,100) coordinate pair. The
pixels might not be drawn depending on your clipping settings, but the
CP is never clipped to clipping boundaries.

The following routines set the CP to the new position:

\begin{itemize}
\item \textit{ClearDevice}
\item \textit{ClearViewPort}
\item \textit{GraphDefaults}
\item \textit{InitGraph}
\item \textit{LineRel}
\item \textit{LineTo}
\item \textit{MoveRel}
\item \textit{MoveTo}
\item \textit{OutText}
\item \textit{SetGraphMode}
\item \textit{SetViewPort}
\end{itemize}

\subsection{Error handling}

There is only basic error checking in the graph unit. To get the value of
the last error returned by a graphics driver call, call the
\textit{GraphResult} routine. The following routines can set error codes,
others don't :

\begin{itemize}
\item \textit{Bar}                      --- ok
\item \textit{Bar3D}                    --- ok
\item \textit{ClearViewPort}
\item \textit{CloseGraph}               --- ok
\item \textit{DetectGraph}              --- ok
\item \textit{DrawPoly}                 --- ok
\item \textit{FillPoly}                 --- ok
\item \textit{FloodFill}                --- ok
\item \textit{GetModeName}              --- ok
\item \textit{GetRGBPalette}            --- ok
\item \textit{InitGraph}                --- ok
\item \textit{InstallUserDriver}        --- ok
\item \textit{InstallUserFont}          --- ok
\item \textit{PieSlice}
\item \textit{RegisterBGIDriver}         --- ok
\item \textit{RegisterBGIFont}           --- ok
\item \textit{SetAllPalette}             --- ok
\item \textit{SetFillPattern}            --- ok
\item \textit{SetFillStyle}              --- ok
\item \textit{SetGraphBufSize}
\item \textit{SetGraphMode}
\item \textit{SetLineStyle}                --- ok
\item \textit{SetPalette}                 --- ok
\item \textit{SetRGBPalette}              --- ok
\item \textit{SetTextJustify}             --- ok
\item \textit{SetTextStyle}               --- ok
\item \textit{SetViewPort}                 --- ok
\end{itemize}

\textit{GraphResult} is reset to zero after it has been called. Therefore
the user should store the value returned by this function into a temporary
variable and then use it.

\subsection{Write modes}

Write modes permits combining colors with already existing on-screen colors,
\textit{PutImage} supports several write modes, while most other routines
support only CopyPut/NormalPut and XORPut modes.

The following routines support XORPut write modes (all routines support
CopyPut modes):

\begin{itemize}
\item \textit{FillEllipse}
\item \textit{FillPoly}
\item \textit{Arc} with ThickWidth line styles only
\item \textit{Circle} with ThickWidth line styles only
\item \textit{Line}
\item \textit{LineRel}
\item \textit{LineTo}
\item \textit{Rectangle}
\item \textit{DrawPoly}
\end{itemize}

\subsection{Text}
An internal bitmap font is included with this implementation of the graph
unit. It also possible to load and use standard Borland CHR external
vectorized font files. A bitmapped font is defined in this case by
a matrix of 8x8 pixels. A vector font (also referred to as a stroked font)
is defined by a series of vectors that tell the graphics system how to draw
the font.

\subsection{Clipping and Viewports}

\textit{SetViewPort} makes all output commands operate in a rectangular
region of the screen. Most output routines are viewport relative until
the viewport is changed. If clipping is active, all graphics is output
is clipped to the current region.

There is always clipping to the screen boundaries, whatever the clipping
setting is.

\subsection{Internals}

To make porting to a new platform easier, some of the graph unit routines
have been designed using procedural variables. Some of the routines have
default hooks, while others must absolutely be implemented for every new
platform to make the graph unit work.

The following routines must be created for every new platform supported:

\begin{itemize}
\item \textit{CloseGraph}
\item \textit{DirectPutPixel}
\item \textit{PutPixel}
\item \textit{GetPixel}
\item \textit{InitMode}
\item \textit{SaveVideoState}
\item \textit{RestoreVideoState}
\item \textit{QueryAdapterInfo}
\item \textit{SetRGBPalette}
\item \textit{GetRGBPalette}
\end{itemize}

The following global variables must be setup for every new platform
supported:
 InternalDriverName

\var{InternalDriverName}

This variable should be set to a string describing the platform driver
name. It is returned by the user function GetDriverName. Some examples
of driver names are 'DosGX', 'DirectX', 'QuickDrw','CyberGFX', 'Dive'.




\var{CloseGraph}

The CloseGraph routine is called directly by the user and must
do the necessary cleanup by freeing up all platform specific
memory allocations, and by calling RestoreVideoState.

\var{DirectPutPixel}

This routine is one of the most important callback routines with
PutPixel, it is called by most of the routines in the graph unit. It
is about the same as PutPixel except that the coordinates passed to
it are already in global (screen) coordinates, and that clipping has
already been performed. Note that the current WriteMode has to be taken
into account in this procedure.

\var{InitMode}

This callback routine is called by SetGraphMode to actualliy change to
the correct video mode. (SetGraphMode is called by InitGraph).

\var{SaveVideoState}

This routine is called by InitGraph before changing to the graphics video
mode, it should save the old video mode, save any internal video state
such as the palette entries.

\var{RestoreVideoState}

This routine should be called by CloseGraph, it should restore the video
mode to the one saved in SaveVideoState, and restore all appropriate video
information, so that the video is in the same state as it was when
SaveVideoState was called.

\var{QueryAdapterInfo}

This routine might be called by the user BEFORE we are in graphics
mode. It is called by the initialization code of the graph unit. It
creates a linked list of video capabilities and procedural hooks for
all supported video modes on the platform. Look at the DOS version,
to see how it works. This linked list can be read by the user before a
call to InitGraph to determine which mode to use.

The linked list is composed of mode information, as well to pointers
to the callback routines cited above. Some additional optional hooks
are also possible for those who wish to optimize the speed of the unit.


-------------------------------------------------------------
\begin{function}{GetModeName}
\Declaration
Function GetModeName (ModeNumber : smallint) : String;

\Description

Returns a string with the name of the specified graphics mode. The
return values are in the form, XRes x YRes NAME. This function is
useful for building menus, display status, and so forth.

\Errors
If the specified \var{ModeNumber} is invalid, the function returns an
empty string and sets GraphResult to grInvalidMode.
\SeeAlso
\seef{GetDriverName}, \seep{GetModeRange}, \seep{GetMaxMode}
\end{function}
------------------------
\begin{procedure}{SetAllPalette}
\Declaration
Procedure SetAllPalette(var Palette: PaletteType) ;
\Description
\var{Palette} is of type PaletteType. The first field in Palette
contains the length of the palette. The next \textit{n} fields of
type \var{RGBRec} contains the Red-Green-Blue components to replace
that specific color with. A value of -1 will not change the previous
entry's value.

Note that valid colors depend on the current graphics mode.

If the number of palette entries to replace is greater then the
number of colors possible on the screen, \var{GraphResult} returns
a value of \var{grError} and no changes to the palette settings will
occur.

Changes to the palette take effect immediately on the screen. Each time
a palette color is changed, that color will be changed to the new color
value.

This routine returns \var{grError} if called in a direct color mode.

\Errors
None.
\SeeAlso
\seep{SetRGBPalette}, \seep{SetPalette}
\end{procedure}
------------------------

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

\Description
Returns a \var{PaletteType} record containing the default RGB color
values when the graphics mode is initialized. These values are based
on the IBM-PC VGA hardware adapter, but do not change from platform
to platform.

On other platforms the colors may not exactly match those
on the IBM-PC, but the match should be close enough for most uses. This
value is static and does never change.

Even if the modes can support more then 256 color entries, only the
256 first colors can be considered as having default values. Therefore,
at most this function will return 256 entries. To query all colors over
256 yourself, use \var{GetRGBPalette} for the entire palette range.

\Errors
None.
\SeeAlso
\seef{GetColor}, \seef{GetBkColor}, \seep{GetRGBPalette}
\end{procedure}


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

\Description
\var{GetPalette} returns in \var{Palette} the current palette. The palette
is in LSB RGB format.

This routine returns \var{grError} if called in a direct color mode.

\Errors
None.
\SeeAlso
\seef{GetPaletteSize}, \seep{SetPalette}
\end{procedure}
---------------------------
---------------------------
\begin{function}{GetBkColor}
\Declaration
Function GetBkColor  : Word;

\Description
\var{GetBkColor} returns the current background color. If in non direct color
mode, this returns the palette entry, otherwise it returns the direct
RGB value of the current drawing color.
\Errors
None.
\SeeAlso
\seef{GetColor},\seep{SetBkColor}
\end{function}
---------------------------
\begin{function}{GetColor}
\Declaration
Function GetColor  : Word;

\Description
\var{GetColor} returns the current drawing color. If in non direct color
mode, this returns the palette entry, otherwise it returns the direct
RGB value of the current drawing color.
\Errors
None.
\SeeAlso
\seef{GetColor},\seep{SetBkColor}
\end{function}
---------------------------
\begin{procedure}{GetRGBPalette}
\Declaration
Procedure GetRGBPalette (ColorNum: intege; var Red,Green,Blue : smallint);

\Description
\var{GetRGBPalette} gets the \var{ColorNum}-th entry in the palette.
The Red , Green and Blue values returned arein LSB format.
If the palette entry could not be read for a reason,
the routine returns \var{grError}.

This routine returns \var{grError} if called in a direct color mode.

\Errors
None.
\SeeAlso
\seep{SetAllPallette},
\seep{SetPalette}
\seep{SetRGBPalette}
\end{procedure}

----------------------------
----------------------------
\begin{procedure}{SetDirectVideo}
\Declaration
Procedure SetDirectVideo (DirectAccess : boolean);

\Description
Determines how the video access should be done, if DirectAccess
is set to TRUE then access will be done directly to video memory, if
it is supported, otherwise Operating systems calls will be done to
access the video memory.

The behaviour of this routine depends on the platform, and is required
for example to use the graph unit under older multitaskers such as
Desqview (DOS platform). Certain modes re simply not supported
via Operating system calls, while others are only supported by the
operating system. In those cases this routine is simply ignored.

Using operating system calls to plot pixels is much slower then using
the direct mode, but it provides more compatibility.

\textbf{Platform specific}
Windows NT, OS/2, Windows '9x, Windows 3.x, Linux DOSEMU support
all \textit{standard} video DOS modes, even in DirectVideo mode.
Others, like Desqview, Topview, DoubleDOS and MultiDOS might not.
In that case, \vaR{SetDirectVideo} should be called and set to FALSE.

VESA modes are not considered as standard DOS video modes,
and should simply not be used under such multitaskers/emulators.

Mode-X is not considered a standard DOS mode, but is supported in
most modern operating systems, since it uses only standard VGA
I/O ports and memory. (Exception: older multitaskers such as Desqview).

NOT IMPLEMENTED YET.


\Errors
None.
\SeeAlso
\seef{GetDirectVideo}
\end{procedure}

----------------------------
\begin{function}{GetDirectVideo}
\Declaration
Function GetDirectVideo : boolean;

\Description
Returns the state of the of DirectAccess flag. If this value returns
TRUE, then in the case where it is possible, the video memory is directly
accessed to plot graphics points, otherwise operating system calls
are used.


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


----------------------------


\section{Reference}




\section{Constants, Types and Variables}
\subsection{Types}
\begin{verbatim}
ArcCoordsType = record
 X,Y,Xstart,Ystart,Xend,Yend : smallint;
end;
FillPatternType = Array [1..8] of Byte;
FillSettingsType = Record
 Pattern,Color : Word
end;
LineSettingsType = Record
  LineStyle,Pattern, Width : Word;
end;



PointType = Record
  X,Y : smallint;
end;
TextSettingsType = Record
 Font,Direction, CharSize, Horiz, Vert : Word
end;
ViewPortType = Record
  X1,Y1,X2,Y2 : smallint;
  Clip : Boolean
end;
\end{verbatim}

\begin{verbatim}
PaletteType = Record
 Size : longint;
 Colors : array[0..MaxColors] of RGBRec;
end;
\end{verbatim}

This record is used by \textit{SetAllPalette} , \textit{GetPalette} and
\textit{GetDefaultPalette}. \textit{Size} indicated the number of RGB
entries in this record, followed by the RGB records for each color. It
is to note, that contrary to Turbo Pascal, the RGB components are in
the LSB's of the RGB component records. This makes easier compatibility
across different hardware platforms.


\section{Functions and procedures}


\begin{procedure}{Arc}
\Declaration
Procedure Arc (X,Y : smallint; stAngle,Endangle, radius : Word);

\Description
 \var{Arc} draws part of a circle with center at \var{(X,Y)}, radius
\var{radius}, starting from angle \var{stAngle}, stopping at angle \var{EndAngle}.
These  angles are measured counterclockwise. Information about the last call
to \var{Arc} can be retrieved by \var{GetArcCoords}.
\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 : smallint);

\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 : smallint; 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 : smallint; Radius : Word);

\Description
 \var{Circle} draws part of a circle with center at \var{(X,Y)}, radius
\var{radius} in the current color. Each graphics driver contains an
aspect ratio used by \var{Circle}, \var{Arc} and \var{PieSlice}.
\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, restores the
screen mode which was active before the graphical mode was
activated and frees up any memory allocated in InitGraph.
\Errors
None.
\SeeAlso
\seep{InitGraph}
\end{procedure}

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

\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 (NumPoints : Word; Var PolyPoints);

\Description

Draws a polygon with \var{NumPoints} corner points, using the
current color and linestyle. PolyPoints is an array of type \var{PointType}.

If there are less the two points in \var{PolyPoints}, this routine
returns \var{grError}.

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

\begin{procedure}{Ellipse}
\Declaration
Procedure Ellipse (X,Y : smallint; StAngle,EndAngle,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{StAngle} and \var{EndAngle} are the starting and stopping angles of
the part of the ellipse. They are measured counterclockwise from the X-axis.

Information about the last call to \var{Ellipse} can be retrieved by
\var{GetArcCoords}.

\Errors
None.
\SeeAlso
\seep{Arc} \seep{Circle}, \seep{FillEllipse}
\end{procedure}
\begin{procedure}{FillEllipse}
\Declaration
Procedure FillEllipse (X,Y : smallint; 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 (NumberPoints : Word; Var PolyPoints);

\Description

Draws a polygon with \var{NumPoints} corner points and fills it
using the current color and fill style. The outline of the polygon
is drawn in the current line style and color as set by \var{SetLineStyle}.
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 : smallint; BorderColor : Word);

\Description

Fills the area containing the point \var{(X,Y)}, bounded by the color
\var{BorderColor}. The flooding is done using the current fill style
and fill color, as set by \var{SetFillStyle} or \var{SetFillPattern}.

This routine is here for compatibility only, \var{FillPoly} should be
used instead, since it is much faster.

\Errors
None
\SeeAlso
\seep{FillPoly},
\end{procedure}

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

\Description
\var{GetArcCoords} returns the coordinates of the last \var{Arc} or
\var{Ellipse} call. The values are useful for connecting a line to
the end of an ellipse.
\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}.

Each graphics driver uses this aspect ratio to make circles and any circular
shape look round on the screen.
\Errors
None.
\SeeAlso
\seep{InitGraph},\seep{SetAspectRatio}
\end{procedure}


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

\Description
\var{GetDriverName} returns a string containing the name of the
current driver. This name can be anything under FPC, but it is
usually indicative of the API and/or platform used to perform the
graphics call.
\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}.
If no user call has been made to \var{SetFillPattern}, the pattern will be
filled with \var{$FF}.

It is to note that the user fill pattern is reset to \var{$FF} each time
\var{GraphDefaults} is called.

\Errors
None
\SeeAlso
\seep{SetFillPattern}, \seep{GraphDefaults}
\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  : smallint;

\Description
\var{GetGraphMode} returns the current graphical mode. This value is
entirely dependant on the hardware platform. To look up what this
mode number represents from a capabilities standpoint, you should
call either \var{QueryAdapterInfo} or \var{GetModeName} with the
value returned by this function.
\Errors
None.
\SeeAlso
\seep{InitGraph}, \seep{QueryAdapterInfo}, \seep{GetModeName}
\end{function}

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

\Description
\var{GetImage}
Places a copy of the screen area \var{(X1,Y1)} to \var{X2,Y2} in \var{BitMap}.
\var{Bitmap} is an untyped parameter that must be equal to 12 plus the size
of the screen area to save. The first two longints of \var{Bitmap} store
the width and height of the region. The third longint is reserved and should
not be modified.

To make access to the screen faster, it is recommended that the starting
points and ending point coordinates be modulo 4 and that the width to
save be also modulo 4.

To get the size of the bitmap required to save the area, you should call
\var{ImageSize}.

\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}. This value is zero based, so a screen
which supports 16 colors, would return 15.

\Errors
None.
\SeeAlso
\seep{SetColor},
\seef{GetPaletteSize}
\end{function}
\begin{function}{GetMaxMode}
\Declaration
Function GetMaxMode  : Word;

\Description
\var{GetMaxMode} returns the highest mode for the current driver. Normally
the higher the mode number, the resolution it will be, but this might not
always be the case.
\Errors
None.
\SeeAlso
\seep{InitGraph}
\end{function}

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

\Description
\var{GetMaxX} returns the maximum horizontal screen
length (zero based from 0..\var{MaxX}).
\Errors
None.
\SeeAlso
\seef{GetMaxY}
\end{function}
\begin{function}{GetMaxY}
\Declaration
Function GetMaxY  : Word;

\Description
\var{GetMaxY} returns the maximum number of screen
lines. (zero based from 0..\var{MaxY}).
\Errors
None.
\SeeAlso
\seef{GetMaxY}
\end{function}

\begin{procedure}{GetModeRange}
\Declaration
Procedure GetModeRange (GraphDriver : smallint; var LoMode, HiMode: smallint);

\Description
\var{GetModeRange} returns the Lowest and Highest mode of the currently
installed driver. If the value of \var{GraphDriver} is invalid, \var{LoMode}
and var{HiMode} are set to -1.
\Errors
None.
\SeeAlso
\seep{InitGraph}, \seep{GetModeName}
\end{procedure}
\begin{function}{GetPaletteSize}
\Declaration
Function GetPaletteSize  : Word;

\Description
\var{GetPaletteSize} returns the maximum number of entries which
can be set in the current palette. In direct color mode, this simply
returns the maximum possible of colors on screen.

Usually this has the value \var{GetMaxColor} + 1.

\Errors
None.
\SeeAlso
\seep{GetPalette},
\seep{SetPalette}
\seep{GetMaxColor}
\end{function}
\begin{function}{GetPixel}
\Declaration
Function GetPixel (X,Y : smallint) : Word;

\Description
\var{GetPixel} returns the color
of the point at \var{(X,Y)} The coordinates, as all coordinates
are viewport relative.

In direct color mode, the value returned is the direct RGB components of
the color. In palette based modes, this indicates the palette entry number.

\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 view-port and clipping settings in
\var{ViewPort}.
\Errors
None.
\SeeAlso
\seep{SetViewPort}
\end{procedure}

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

\Description
\var{GetX} returns the X-coordinate of the current pointer. This value is
viewport relative.
\Errors
None.
\SeeAlso
\seef{GetY}
\end{function}
\begin{function}{GetY}
\Declaration
Function GetY  : smallint;

\Description
\var{GetY} returns the Y-coordinate of the current pointer. This value is
viewport relative.
\Errors
None.
\SeeAlso
\seef{GetX}
\end{function}
\begin{procedure}{GraphDefaults}
\Declaration
Procedure GraphDefaults ;

\Description
\var{GraphDefaults} homes the current pointer, and resets the graphics
system to the default values for:

\begin{itemize}
 \item Active Line style is reset to normal width and filled line.
 \item The current fill color is set to the maximum palette color.
 \item The current fill style is set to \var{solidfill}.
 \item The user fill pattern is reset to \var{$FF}.
 \item The current drawing color is set to white.
 \item The current background color is reset to black.
 \item The viewport is reset to (0,0,\var{GetMaxX},\var{GetMaxY}).
 \item Clipping is enabled.
 \item The active write mode is set to normalput.
 \item Text settings are reset to : default font, \var{HorizDir},
         \var{LeftText} and \var{TopText}.
\end{itemize}

This routine is called by \var{SetGraphMode}.

\Errors
None.
\SeeAlso
\seep{SetViewPort}, \seep{SetFillStyle}, \seep{SetColor},
\seep{SetBkColor}, \seep{SetLineStyle}, \seep{SetGraphMode}
\end{procedure}

\begin{function}{GraphErrorMsg}
\Declaration
Function GraphErrorMsg (ErrorCode : smallint) : 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  : smallint;

\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.

Note that \var{GraphResult} is reset to zero after it has been called.
Therefore the value should be saved into a temporary location if you wish
to use it later.

To see which routine might return errors, see the introduction section at
the start of this reference.

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

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

\Description
\var{ImageSize} returns the number of bytes needed to store the image
by \var{GetImage} in the rectangle defined by \var{(X1,Y1)} and \var{(X2,Y2)}.
The image size includes space for several words. The first three longints
are reserved for use by \var{GetImage}, the first longint containing the
width of the region, the second containing the height, and the third being
reserved,the following words contains the bitmap itself.

\textit{Compatibility:}
 The value returned by this function is a 32-bit value,
 and not a 16-bit value.

\Errors
None.
\SeeAlso
\seep{GetImage}
\end{function}

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

\Description

\var{InitGraph} initializes the \var{graph} package.

\var{GraphDriver} has two valid values: \var{GraphDriver=Detect} which
performs an auto detect and initializes the highest possible mode with the most
colors. This is dependant on the platform, and many of the non-standard
modes amy not be detected automatically. \var{graphMode} is the mode you
wish to use.

\var{PathToDriver} is only needed, if you use the BGI fonts from
Borland, which are fully supported under FPC.

The exact rundown of \var{InitGraph} is as follows: First it calls
\var{QueryAdapterInfo} to get the possible modes supported by the hardware.
It then saves the video state, initalizes some global variables, then if
auto-detection was requested, calls \var{GetModeRange} to get the highest
possible mode available and supported, otherwise it searches if the requested
mode is available in the database. Finally , in either case it calls
\var{SetGraphMode}.

If the requested driver or mode is invalid, this function returns either
\var{grError} or \var{grInvalidMode}.

Before calling this function, you should call QueryAdapterInfo, and
go through the list of supported modes to determine which mode suites
your needs. As stated in the introduction, each graph unit implementation
should support a 320x200 color mode.

\Errors
None.
\SeeAlso
Introduction, (page \pageref{se:Introduction}),
\seep{DetectGraph}, \seep{CloseGraph}, \seef{GraphResult},
\seef{QueryAdapterInfo}
\end{procedure}
Example:
\begin{verbatim}
var
   gd,gm : smallint;
   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) : smallint;

\Description
This routine is not supported in FPC, it is here only for compatiblity and
always returns \var{grError}.

\Errors
None.
\SeeAlso
\seep{InitGraph}, \seef{InstallUserFont}
\end{function}
\begin{function}{InstallUserFont}
\Declaration
Function InstallUserFont (FontPath : String) : smallint;

\Description
\var{InstallUserFont} adds the font in \var{FontPath} to the list of fonts
available to the text system. If the maximum number of allocated fonts has
been reached, this routine sets \var{GraphResult} to \var{grError}.
\Errors
None.
\SeeAlso
\seep{InitGraph}, \seef{InstallUserDriver}
\end{function}
\begin{procedure}{Line}
\Declaration
Procedure Line (X1,Y1,X2,Y2 : smallint);

\Description
\var{Line} draws a line starting from
\var{(X1,Y1} to \var{(X2,Y2)}, in the current line style and color.
The current pointer is not updated after this call.

This is the base routine which is called by several other routines
in this unit. This routine is somewhat faster then the other
LineXXX routines contained herein.


\Errors
None.
\SeeAlso
\seep{LineRel},\seep{LineTo}
\end{procedure}
\begin{procedure}{LineRel}
\Declaration
Procedure LineRel (DX,DY : smallint);

\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 : smallint);

\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 : smallint;

\Description
\var{MoveRel} moves the current 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 : smallint);

\Description
\var{MoveTo} moves the current 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 pointer is
updated only if the text justification is set to left and is horizontal.

The text is truncated according to the current viewport settings if it
cannot fit.

In order to maintain compatibility when using several fonts, use \var{TextWidth}
and \var{TextHeight} calls to determine the dimensions of the string.

\Errors
None.
\SeeAlso
\seep{OutTextXY}
\end{procedure}
\begin{procedure}{OutTextXY}
\Declaration
Procedure OutTextXY (X,Y : smallint; Const TextString : String);

\Description
\var{OutText} puts \var{TextString} on the screen, at position \var{(X,Y)},
using the current font and text settings.

Contrary to \var{OutText} , this routine does not update the current pointer.

In order to maintain compatibility when using several fonts, use \var{TextWidth}
and \var{TextHeight} calls to determine the dimensions of the string.

\Errors
None.
\SeeAlso
\seep{OutText}
\end{procedure}
\begin{procedure}{PieSlice}
\Declaration
Procedure PieSlice (X,Y,stangle,endAngle:smallint;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{StAngle} and ending at angle \var{EndAngle}
using the current fill style and fill pattern. The pie slice is outlined
with the current line style and current active color.
\Errors
None.
\SeeAlso
\seep{Arc}, \seep{Circle}, \seep{Sector}
\end{procedure}
\begin{procedure}{PutImage}
\Declaration
Procedure PutImage (X,Y: smallint; var Bitmap; BitBlt: Word);

\Description
\var{PutImage}
Places the bitmap in \var{Bitmap} on the screen at upper left
corner \var{(X, Y)}. \var{BitBlt} 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}

\textit{Compatibility}

Contrary to the Borland graph unit, putimage \textit{is} clipped to the
viewport boundaries.

\Errors
None
\SeeAlso
\seef{ImageSize},\seep{GetImage}
\end{procedure}
\begin{procedure}{PutPixel}
\Declaration
Procedure PutPixel (X,Y : smallint; Color : Word);

\Description
Puts a point at
\var{(X,Y)} using color \var{Color}. This routine is viewport
relative.
\Errors
None.
\SeeAlso
\seef{GetPixel}
\end{procedure}
\begin{procedure}{Rectangle}
\Declaration
Procedure Rectangle (X1,Y1,X2,Y2 : smallint);

\Description
Draws a rectangle with
corners at \var{(X1,Y1)} and \var{(X2,Y2)}, using the current color and
the current line style.
\Errors
None.
\SeeAlso
\seep{Bar}, \seep{Bar3D}
\end{procedure}
\begin{function}{RegisterBGIDriver}
\Declaration
Function RegisterBGIDriver (Driver : Pointer) : smallint;

\Description
This routine is not supported in FPC. It is here for compatibility and it
always returns \var{grError}.
\Errors
None.
\SeeAlso
\seef{InstallUserDriver},
\seef{RegisterBGIFont}
\end{function}
\begin{function}{RegisterBGIFont}
\Declaration
Function RegisterBGIFont (Font : Pointer) : smallint;

\Description
This routine permits the user to add a font to the list of known fonts
by the graph unit. \var{Font} is a pointer to image of the loaded font.

The value returned is either a negative error number (\var{grInvalidFont}),
or the font number you need to use when accessing it via \var{SetTextStyle}.

This routine may be called before \var{InitGraph}.


\textit{Compatibility}
Watch out for the byte endian when using this routine. This might work
on little endian machines, and not on big endian machines and vice-versa.


\Errors
None.
\SeeAlso
\seef{InstallUserFont},
\seef{RegisterBGIDriver}
\end{function}
\begin{procedure}{RestoreCRTMode}
\Declaration
Procedure RestoreCRTMode ;

\Description
Restores the screen mode which was active before
the graphical mode was started. Can be used to switch back and forth
between text and graphics mode.
\Errors
None.
\SeeAlso
\seep{InitGraph}


\end{procedure}

Example:
\begin{verbatim}
uses Graph;

var
 Gd, Gm: smallint;
 Mode: smallint;
begin
 Gd := Detect;
 InitGraph(Gd, Gm, ' ');
 if GraphResult <> grOk then
   Halt(1);
 OutText('<ENTER> to leave graphics:');
 Readln;
 RestoreCrtMode;
 Writeln('Now in text mode');
 Write('<ENTER> to enter graphics mode:');
 Readln;
 SetGraphMode(GetGraphMode);
 OutTextXY(0, 0, 'Back in graphics mode');
 OutTextXY(0, TextHeight('H'), '<ENTER> to quit:');
 Readln;
 CloseGraph;
end.
\end{verbatim}
\begin{procedure}{Sector}
\Declaration
Procedure Sector (X,Y : smallint; StAngle,EndAngle,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{StAngle} and ending at angle
\var{EndAngle}. The sector is outlined in the current color and filled with
the pattern and color defined by \var{SetFillStyle} or \var{SetFillPattern}.
\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. This means that all drawing will be done on this
graphics, be it visible or not.

The usual way to make fast animation, is to draw to a non visible active page
and the simply call make that active page the visible page by calling
\var{SetVisualPage}.

\textit{Compatibility}:
Not all systems and graphics mode support multiple graphics pages, to
determine how many pages are available see \var{QueryAdapterInfo}.

Multiple pages are currently not supported with DOS VESA modes.

\Errors
None.
\SeeAlso
\seep{SetVisualPage}, \seep{QueryAdapterInfo}

\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} which contains the Red, Green and Blue
components of the RGB components to change for each color entry. If
the Red, Green and Blue components are equal to -1 for a specific color
entry, then that palette entry will not be changed. The size should
contain the size of the palette to change (indexed at zero).

\textit{Compatibility}:

This call is not the same as in Turbo Pascal. RGB components should be
set in LSB if each of the components has less then 16-bits resolution.

This call is not supported in direct color modes.

\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}. The value of the aspect ratio is used
by certain routines herein to draw circles which will actually appear round
depending on the screen mode.
\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}.

The behaviour of this routine depends if we are in a direct color
mode or not. In direct color mode, this value represents the direct
RGB values to plot to the screen. In non direct color mode, the value
represents an index to the color palette entry on the hardware.

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

The behaviour of this routine depends if we are in a direct color
mode or not. In direct color mode, this value represents the direct
RGB values to plot to the screen. In non direct color mode, the value
represents an index to the color palette entry on the hardware.

\Errors
None.
\SeeAlso
\seef{GetColor}, \seep{SetBkColor}
\end{procedure}
\begin{procedure}{SetFillPattern}
\Declaration
Procedure SetFillPattern (Pattern : FillPatternType, Color : Word);

\Description
\var{SetFillPattern} sets the current fill-pattern to \var{Pattern}, and
the filling color to \var{Color}. If invalid input is passed to
\var{SetFillPattern}, \var{GraphResult} will return \var{grError}.

The pattern is an 8x8 raster, corresponding to the 64 bits in
\var{FillPattern}. Whenever a bit in a pattern byte is valued at 1,
a pixel will be plotted. The pattern and color is used by \var{Bar},
\var{FillPoly}, \var{FloodFill}, \var{bar3d}, \var{FillEllipse},
\var{Sector}, and \var{PieSlice}.


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

If invalid input is passed to \var{SetFillStyle},
\var{GraphResult} will return \var{grError}.

\Errors
None.
\SeeAlso
\seep{SetFillPattern}
\end{procedure}
\begin{procedure}{SetGraphBufSize}
\Declaration
Procedure SetGraphBufSize (BufSize : Word);

\Description
This routine does nothing in FPC, and is here for compatibility.
\Errors
None.
\SeeAlso

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

\Description
\var{SetGraphMode} sets the
graphical mode and clears the screen. \var{Mode} must be a valid mode,
which can be queried by \var{QueryAdapterInfo}.

If invalid input is passed to \var{SetGraphMode}, or if the mode cannot
be set for a reason, \var{GraphResult} returns \var{grInvalidMode}.

\var{SetGraphMode} resets all graphics variables to their default
settings (such as if \var{GraphDefaults} was called, the active page
is reset to page zero, the visual page is reset to page zero, and the viewport
is set to the entire screen.

\Errors
None.
\SeeAlso
\seep{InitGraph}, \seep{QueryAdapterInfo}
\end{procedure}
\begin{procedure}{SetLineStyle}
\Declaration
Procedure SetLineStyle (LineStyle, Pattern, Thickness : 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 to
use for drawing the line. A bit of 1 specified a pixel which is on.

In all another cases, \var{Pattern} is ignored. The parameter \var{Thickness}
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}

If invalid input is passed to \var{SetLineStyle} , \var{GraphResult} will
return \var{grError}.

\Errors
None.
\SeeAlso
\seep{GetLineSettings}
\end{procedure}
\begin{procedure}{SetPalette}
\Declaration
Procedure SetPalette (ColorNum : Word; Color : Shortint);

\Description
\var{SetPalette} changes the \var{ColorNum}-th entry in the palette to
\var{Color}. For examples, \var{SetPalette(0, LightCyan)} makes the first
color in the palette light cyan. \var{Color} only accepts certain default
colors, as specified in the \var{Color constants} section. If invalid
input is passed to \var{SetPalette}, \var{GraphResult} returns a value
of \var{grError} and the palette remains intact.

Changes made to the palette are immediately visible on the screen.

This routine returns \var{grError} if called in a direct color mode.

\Errors
None.
\SeeAlso
\seep{SetAllPallette},\seep{SetRGBPalette}
\end{procedure}
\begin{procedure}{SetRGBPalette}
\Declaration
Procedure SetRGBPalette (ColorNum,Red,Green,Blue : smallint);

\Description
\var{SetRGBPalette} sets the \var{ColorNum}-th entry in the palette to the
color with RGB values \var{Red, Green Blue}. The Red , Green and Blue values
must be in LSB format. If the palette entry could not be changed for a
reason, the routine returns \var{grError}.

This routine returns \var{grError} if called in a direct color mode.

\Errors
None.
\SeeAlso
\seep{SetAllPallette},
\seep{SetPalette}
\seep{GetRGBPalette}
\end{procedure}
\begin{procedure}{SetTextJustify}
\Declaration
Procedure SetTextJustify (Horiz, Vert : Word);

\Description
\var{SetTextJustify} controls the placement of new text, relative to the
(graphical) cursor position. \var{Horiz} 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 current pointer.
\item \var{CenterText=1;} Text is set centered horizontally on the current pointer.
\item \var{RightText=2;} Text is set to the right of the current 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 current pointer.
\item \var{CenterText=1;} Text is placed centered vertically on the current pointer.
\item \var{TopText=2;}Text is placed above the current pointer.
\end{itemize}

If invalid input is passed \var{SetTextJustify} , \var{GraphResult} returns
\var{grError}.

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

Charsize indicated the magnification factor to use when drawing the fonts
to the screen. When using the default internal font, this value can be
any value equal or greater to one. In the case of stroked fonts, the
value should always be equal or greater then 4.

Stroked fonts are usually loaded from disk once onto the heap when a call
is made to \var{SetTextStyle}.

If there is an error when using this routine, \var{GraphResult} might return
\var{grFontNotFound}, \var{grNoFontMem}, \var{grError}, \var{grIoError},
\var{grInvalidFont}, or \var{grInvalidFontNum}.

\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 : smallint; Clip : Boolean);

\Description
Sets the current graphical view-port (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 view-port (window) will be
clipped (i.e. not drawn). Coordinates specified after this call are relative
to the top-left corner of the view-port.
\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 : smallint);

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

If you specify another mode, it is mapped to one of the above acoording to
the following table (for TP compatibility, may be changed in the future):
\begin{itemize}
\item Notput, Orput: CopyPut
\item AndPut: XorPut
\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}