% % $Id$ % This file is part of the FPC documentation. % Copyright (C) 1997,1999 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 HercMono & HercMonoHi & 720x348 & 1 \\ VGA & VGAHi & 640x480 & 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{FillEllipse}. \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} \item \textit{DetectGraph} \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{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. \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. In all cases it is called by DetectGraph and InitGraph. 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 : Integer) : 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. Thie 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}{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}{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{procedure}{SetRGBPalette} \Declaration Procedure SetRGBPalette (ColorNum,Red,Green,Blue : Integer); \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{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 : Integer); \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}{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}{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} \section{Reference} \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; 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} \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 : Integer; 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 : 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} 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 : 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 (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 : Integer; 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 : 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 (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 : Integer; 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 : Integer; \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 : Integer, 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 : Integer; var LoMode, HiMode: Integer); \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 : Integer) : 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 : Integer; \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 : Integer; \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 : 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. Note that \var{GraphResult} is reset to zero after it has been called. Therefore the value should be saved into a temporary location if he wishes 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 : Integer) : 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 : integer;\\ 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 sets your needs the best. \Errors None. \SeeAlso Introduction, (page \pageref{se:Introduction}), \seep{DetectGraph}, \seep{CloseGraph}, \seef{GraphResult}, \seef{QueryAdapterInfo} \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 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) : Integer; \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 : 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 pointer is not updated after this call. \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 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 : 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 pointer 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. \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}{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} sets the graphical buffer size. The default size is 4Kb \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}{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 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 : 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}