fpc/docs/video.tex

%
%   $Id$
%   This file is part of the FPC documentation.
%   Copyright (C) 1997, by Michael Van Canneyt
%
%   The FPC documentation is free text; you can redistribute it and/or
%   modify it under the terms of the GNU Library General Public License as
%   published by the Free Software Foundation; either version 2 of the
%   License, or (at your option) any later version.
%
%   The FPC Documentation is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
%   Library General Public License for more details.
%
%   You should have received a copy of the GNU Library General Public
%   License along with the FPC documentation; see the file COPYING.LIB.  If not,
%   write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
%   Boston, MA 02111-1307, USA.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 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.

The working of the \file{Video} is simple: After calling \seep{InitVideo},
the array \var{VideoBuf} contains a representation of the video screen of
size \var{ScreenWidth*ScreenHeight}, going from left to right and top to
bottom when walking the array elements: \var{VideoBuf[0]} contains the 
character and color code of the top-left character on the screen.
\var{VideoBuf[ScreenWidth]} contains the data for the character in the
first columnd of the second row on the screen, and so on.

The contents of the \var{VideoBuf} array may be modified: This is 'writing'
to the screen. As soon as everything that needs to be written in the array
is in the \var{VideoBuf} array, calling \var{UpdateScreen} will copy the
contents of the array screen to the screen, in a manner that is as efficient
as possible.

The updating of the screen can be prohibited to optimize performance; To
this end, the \seep{LockScreenUpdate} function can be used: This will
increment an internal counter. As long as the counter different from zero,
calling \seep{UpdateScreen} will not do anything. The counter can be
lowered with \seep{UnLockscreenUpdate}. When it reaches zero, the next call
to \seep{UpdateScreen} will actually update the screen. This is useful when
having nested procedures that do a lot of screen writing.

The video unit also presents an interface for custom screen drivers, thus
it is possible to override the default screen driver with a custom screen 
driver, see the \seep{SetVideoDriver} call.

\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 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
\var{DefaultErrorHandler} is the default error handler used by the video
driver. It simply sets the error code \var{AErrorCode} and \var{AErrorInfo} 
in the global variables \var{ErrorCode} and \var{ErrorInfo} and returns 
\var{errContinue}.
\Errors
None.
\SeeAlso
\end{procedure}

\begin{procedure}{DefaultVideoModeSelector}
\Declaration
function DefaultVideoModeSelector(const VideoMode: TVideoMode; Params: Longint): Boolean;
\Description
Needs to be removed from the API.
\Errors
\SeeAlso
\end{procedure}

\begin{procedure}{DoneVideo}
\Declaration
procedure DoneVideo; 
\Description
\var{DoneVideo} disables the Video driver if the video driver is active. If
the videodriver was already disabled or not yet initialized, it does
nothing. Disabling the driver means it will clean up any allocated
resources, possibly restore the screen in the state it was before
\var{InitVideo} was called.
\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}