+Initial check-in

docs/video.tex

@@ -0,0 +1,357 @@
+%
+%   $Id$
+%   This file is part of the FPC documentation.
+%   Copyright (C) 1997, by Michael Van Canneyt
+%
+%   The FPC documentation is free text; you can redistribute it and/or
+%   modify it under the terms of the GNU Library General Public License as
+%   published by the Free Software Foundation; either version 2 of the
+%   License, or (at your option) any later version.
+%
+%   The FPC Documentation is distributed in the hope that it will be useful,
+%   but WITHOUT ANY WARRANTY; without even the implied warranty of
+%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+%   Library General Public License for more details.
+%
+%   You should have received a copy of the GNU Library General Public
+%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
+%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+%   Boston, MA 02111-1307, USA.
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% The Video unit
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\chapter{The VIDEO unit}
+\FPCexampledir{videoex}
+
+The \file{Video} unit implements a screen access layer which is system
+independent. It can be used to write on the screen in a system-independent
+way, which should be optimal on all platforms for which the unit is
+implemented.
+
+\section{Constants, Type and variables }
+
+\subsection{Constants}
+The following constants describe colors that can be used as 
+foreground and background colors.
+\begin{verbatim}
+Black         = 0;
+Blue          = 1;
+Green         = 2;
+Cyan          = 3;
+Red           = 4;
+Magenta       = 5;
+Brown         = 6;
+LightGray     = 7;
+\end{verbatim}
+The following color constants can be used only as foreground colors:
+\begin{verbatim}
+DarkGray      = 8;
+LightBlue     = 9;
+LightGreen    = 10;
+LightCyan     = 11;
+LightRed      = 12;
+LightMagenta  = 13;
+Yellow        = 14;
+White         = 15;
+\end{verbatim}
+The foreground color can be logically or-ed with the blink attribute:
+\begin{verbatim}
+Blink         = 128;
+\end{verbatim}
+The following constants describe the capabilities of a certain video mode:
+\begin{verbatim}
+cpUnderLine     = $0001;
+cpBlink         = $0002;
+cpColor         = $0004;
+cpChangeFont    = $0008;
+cpChangeMode    = $0010;
+cpChangeCursor  = $0020;
+\end{verbatim}
+The following constants describe the various supported cursor modes:
+\begin{verbatim}
+crHidden        = 0;
+crUnderLine     = 1;
+crBlock         = 2;
+crHalfBlock     = 3;
+\end{verbatim}
+When a video function needs to report an error condition, the following
+constants are used:
+\begin{verbatim}
+vioOK              = 0;
+errVioBase         = 1000;
+errVioInit         = errVioBase + 1; { Initialization error}
+errVioNotSupported = errVioBase + 2; { Unsupported function }
+errVioNoSuchMode   = errVioBase + 3; { No such video mode }
+\end{verbatim}
+The following constants can be read to get some information about the
+current screen:
+\begin{verbatim}
+ScreenWidth     : Word = 0;
+ScreenHeight    : Word = 0;
+LowAscii        : Boolean = true;
+NoExtendedFrame : Boolean = false;
+FVMaxWidth      = 132;
+\end{verbatim}
+The error-handling code uses the following constants:
+\begin{verbatim}
+errOk              = 0;
+ErrorCode: Longint = ErrOK;
+ErrorInfo: Pointer = nil;
+ErrorHandler: TErrorHandler = DefaultErrorHandler;
+\end{verbatim}
+The \var{ErrorHandler} variable can be set to a custom-error handling
+function. It is set by default to the \seef{DefaultErrorHandler} function.
+
+The \var{Modes} list contains the list of supported video modes:
+\begin{verbatim}
+Modes: PVideoModeList = nil;
+\end{verbatim}
+
+\subsection{Types}
+The \var{TVideoMode} record describes a videomode. Its fields are
+self-explaining. The \var{TVideoModeSelector} procedural variable
+is used to select a video mode.
+\begin{verbatim}
+  PVideoMode = ^TVideoMode;
+  TVideoMode = record
+    Col,Row : Word;
+    Color   : Boolean;
+  end;
+  TVideoModeSelector = function (const VideoMode: TVideoMode; Params: Longint): Boolean;
+\end{verbatim}
+\var{TVideoCell} describes one character on the screen. The high byte
+contains the color attribute with which the character is drawn on the screen,
+and the low byte contains the ASCII code of the character to be drawn.
+\begin{verbatim}
+TVideoCell = Word;
+PVideoCell = ^TVideoCell;
+\end{verbatim}
+The \var{TVideoBuf} and \var{PVideoBuf} are two types used to represent the
+screen.
+\begin{verbatim}
+TVideoBuf = array[0..32759] of TVideoCell;
+PVideoBuf = ^TVideoBuf;
+\end{verbatim}
+When registering video modes, the following typed are used to store the
+registered modes:
+\begin{verbatim}
+PVideoModeList = ^TVideoModeList;
+TVideoModeList = record
+  Col, Row: Word;
+  Color: Boolean;
+  VideoModeSelector: TVideoModeSelector;
+  Params: Longint;
+  Next: PVideoModeList;
+end;
+\end{verbatim}
+The following type is used when reporting error conditions:
+\begin{verbatim}
+TErrorHandlerReturnValue = (errRetry, errAbort, errContinue);
+\end{verbatim}
+Here, \var{errRetry} means retry the operation, \var{errAbort}
+abort and return error code and \var{errContinue} means abort
+without returning an errorcode.
+
+The \var{TErrorHandler} function is used to register an own error
+handling function. It should be used when installing a custom error
+handling function, and must return one of the above values.
+\begin{verbatim}
+TErrorHandler = 
+  function (Code: Longint; Info: Pointer): TErrorHandlerReturnValue;
+\end{verbatim}
+\var{Code} should contain the error code for the error condition, 
+and the \var{Info} parameter may contain any data type specific to 
+the error code passed to the function.
+
+\subsection{Variables}
+The following variables contain information about the current screen
+status:
+\begin{verbatim}
+ScreenColor      : Boolean;
+CursorX, CursorY : Word;
+\end{verbatim}
+\var{ScreenColor} indicates whether the current screen supports colors.
+\var{CursorX,CursorY} contain the current cursor position.
+
+The \var{LockUpdateScreen} variable can be incremented to prevent the 
+\seep{UpdateScreen} procedure from actually updating the screen. The 
+\var{UpdateScreen} procedure will only update the screen when the
+\var{LockUpdateScreen} variable is zero. This mechanism can be used
+to optimize the screen updating routines when various updates are 
+performed at once.
+\begin{verbatim}
+LockUpdateScreen : Word;
+CursorLines  : Byte;
+\end{verbatim}
+The following variables form the heart of the \file{Video} unit: The
+\var{VideoBuf} array represents the physical screen. Writing to this
+array and calling \seep{UpdateScreen} will write the actual characters
+to the screen. \var{VideoBufSize} contains the actual screen size, and is
+equal to the product of the number of columns times the number of lines 
+on the screen (\var{ScreenWidth*ScreenHeight}).
+\begin{verbatim}
+VideoBuf     : PVideoBuf;
+VideoBufSize : Longint;
+\end
+\end{verbatim}
+
+\section{Functions and Procedures}
+
+\begin{procedure}{ClearScreen}
+\Declaration
+procedure ClearScreen; 
+\Description
+\var{ClearScreen} clears the entire screen, and calls \seep{UpdateScreen}
+after that.
+\Errors
+None.
+\SeeAlso
+\seep{InitVideo}, \seep{UpdateScreen}
+\end{procedure}
+
+\begin{procedure}{DefaultErrorHandler}
+\Declaration
+function  DefaultErrorHandler(AErrorCode: Longint; AErrorInfo: Pointer): TErrorHandlerReturnValue; 
+\Description
+{ Default error handler, simply sets error code, and returns errContinue }
+\Errors
+\SeeAlso
+\end{procedure}
+
+\begin{procedure}{DefaultVideoModeSelector}
+\Declaration
+function  DefaultVideoModeSelector(const VideoMode: TVideoMode; Params: Longint): Boolean;
+\Description
+\Errors
+\SeeAlso
+\end{procedure}
+
+\begin{procedure}{DoneVideo}
+\Declaration
+procedure DoneVideo; 
+\Description
+{ Deinitializes the video subsystem }
+\Errors
+\SeeAlso
+\end{procedure}
+
+\begin{function}{GetCapabilities}
+\Declaration
+function  GetCapabilities: Word; 
+\Description
+{ Return the capabilities of the current environment }
+\Errors
+\SeeAlso
+\end{function}
+
+\begin{function}{GetCursorType}
+\Declaration
+function GetCursorType: Word; 
+\Description
+{ Return the cursor type: Hidden, UnderLine or Block }
+\Errors
+\SeeAlso
+\end{function}
+
+\begin{procedure}{GetVideoMode}
+\Declaration
+procedure GetVideoMode(var Mode: TVideoMode); 
+\Description
+{ Return dimensions of the current video mode }
+\Errors
+\SeeAlso
+\end{procedure}
+
+\begin{procedure}{InitVideo}
+\Declaration
+procedure InitVideo; 
+\Description
+{ Initializes the video subsystem }
+\Errors
+\SeeAlso
+\end{procedure}
+
+\begin{procedure}{RegisterVideoMode}
+\Declaration
+procedure RegisterVideoMode(Col, Row: Word; Color: Boolean; VideoModeSelector: TVideoModeSelector; Params: Longint); 
+\Description
+{ Registers a video mode to be selectable by SetVideoMode } 
+{ moved to interface because we need a way to retrieve the modes }
+\Errors
+\SeeAlso
+\end{procedure}
+
+\begin{procedure}{SetCursorPos}
+\Declaration
+procedure SetCursorPos(NewCursorX, NewCursorY: Word); 
+\Description
+{ Position the cursor to the given position }
+\Errors
+\SeeAlso
+\end{procedure}
+
+\begin{procedure}{SetCursorType}
+\Declaration
+procedure SetCursorType(NewType: Word); 
+\Description
+\var{SetCursorType} sets the cursor to the type specified in \var{NewType}.
+\begin{description}
+\item[crHidden] the cursor is not visible.
+\item[crUnderLine] the cursor is a small underline character (usually 
+denoting insert mode).
+\item[crBlock] the cursor is a block the size of a screen cell (usually
+denoting overwrite mode).
+\item[crHalfBlock] the cursor is a block half the size of a screen cell.
+\end{description}
+\Errors
+None.
+\SeeAlso
+\seep{SetCursorPos}
+\end{procedure}
+
+\begin{procedure}{SetVideoMode}
+\Declaration
+procedure SetVideoMode(Mode: TVideoMode); 
+\Description
+\var{SetVideoMode} sets the video mode to the mode specified in \var{Mode}:
+\begin{verbatim}
+  TVideoMode = record
+    Col,Row : Word;
+    Color   : Boolean;
+  end;
+\end{verbatim}
+If the call was succesful, then the screen will have \var{Col} columns and
+\var{Row} rows, and will be displaying in color if \var{Color} is
+\var{True}.
+Note that the video mode may not always be set. E.g. a console on Linux
+or a telnet session cannot always set the mode. It is important to check
+the error value returned by this function if it was not succesful.
+\Errors
+If the specified mode cannot be set, then \var{errVioNoSuchMode} may be set
+in \var{ErrorCode}
+\SeeAlso
+\end{procedure}
+
+\begin{procedure}{UpdateScreen}
+\Declaration
+procedure UpdateScreen(Force: Boolean); 
+\Description
+\var{UpdateScreen} synchronizes the actual screen with the contents
+of the \var{VideoBuf} internal buffer. The parameter \var{Force}
+specifies whether the whole screen has to be redrawn (\var{Force=True})
+or only parts that have changed since the last update of the screen.
+
+The \var{Video} unit keeps an internal copy of the screen as it last 
+wrote it to the screen. The current contents of \var{VideoBuf} are examined
+to see what locations on the screen need to be updated. On slow terminals
+(e.g. a \linux telnet session) this mechanism can speed up the screen redraw
+considerably.
+\Errors
+None.
+\SeeAlso
+\seep{ClearScreen}
+\end{procedure}
+