+ Added examples

docs/video.tex

@@ -37,7 +37,19 @@ 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.
+first column of the second row on the screen, and so on.
+
+The color attribute is a combination of the foreground and background color,
+plus the blink bit. The bits descrie the various color combinations:
+\begin{description}
+\item[bits 0-3] The foreground color. Can be set using all color constants. 
+\item[bits 4-6] The background color. Can be set using a subset of the
+color constants.
+\item[bit 7] The blinking bit. If this bit is set, the character will appear
+blinking.
+\end{description}
+Each possible color has a constant associated with it, see page
+\pageref{vidcolorconst} for a list of constants.
 
 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
@@ -49,17 +61,24 @@ 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
+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.
+driver, see the \seef{SetVideoDriver} call. The current video driver can
+be retrieved using the \seep{GetVideoDriver} call.
+
+\begin{remark}
+The video unit should {\em not} be used together with the \file{crt} unit.
+Doing so will result in very strange behaviour, possibly program crashes.
+\end{remark}
 
 \section{Constants, Type and variables }
 
 \subsection{Constants}
+\label{vidcolorconst}
 The following constants describe colors that can be used as 
 foreground and background colors.
 \begin{verbatim}
@@ -72,7 +91,7 @@ Magenta       = 5;
 Brown         = 6;
 LightGray     = 7;
 \end{verbatim}
-The following color constants can be used only as foreground colors:
+The following color constants can be used as foreground colors only:
 \begin{verbatim}
 DarkGray      = 8;
 LightBlue     = 9;
@@ -83,10 +102,18 @@ LightMagenta  = 13;
 Yellow        = 14;
 White         = 15;
 \end{verbatim}
-The foreground color can be logically or-ed with the blink attribute:
+The foreground and background color can be combined to a color attribute
+with the following code:
+\begin{verbatim}
+Attr:=ForeGroundColor + (BackGroundColor shr 4);
+\end{verbatim}
+The color attribute can be logically or-ed with the blink attribute to
+produce a blinking character:
 \begin{verbatim}
 Blink         = 128;
 \end{verbatim}
+But not all drivers may support this.
+
 The following constants describe the capabilities of a certain video mode:
 \begin{verbatim}
 cpUnderLine     = $0001;
@@ -129,7 +156,7 @@ 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.
+function. It is set by default to the \seep{DefaultErrorHandler} function.
 
 The \var{Modes} list contains the list of supported video modes:
 \begin{verbatim}
@@ -138,15 +165,15 @@ Modes: PVideoModeList = nil;
 
 \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.
+self-explaining: \var{Col,Row} describe the number of columns and 
+rows on the screen for this mode. \var{Color} is \var{True} if this mode
+supports colors, or \var{False} if not.
 \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,
@@ -161,18 +188,6 @@ screen.
 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);
@@ -210,9 +225,16 @@ equal to the product of the number of columns times the number of lines
 on the screen (\var{ScreenWidth*ScreenHeight}).
 \begin{verbatim}
 VideoBuf     : PVideoBuf;
+OldVideoBuf  : PVideoBuf;
 VideoBufSize : Longint;
-\end
 \end{verbatim}
+The \var{OldVideoBuf} contains the state of the video screen after the last
+screen update. The \seep{UpdateScreen} function uses this array to decide
+which characters on screen should be updated, and which not. 
+
+Note that the \var{OldVideoBuf} array may be ignored by some drivers, so
+it should not be used. The Array is in the interface section of the video
+unit mainly so drivers that need it can make use of it. 
 
 \section{Functions and Procedures}
 
@@ -221,13 +243,16 @@ VideoBufSize : Longint;
 procedure ClearScreen; 
 \Description
 \var{ClearScreen} clears the entire screen, and calls \seep{UpdateScreen}
-after that.
+after that. This is done by writing spaces to all character cells of the
+video buffer in the default color (lightgray on black, color attribute \$07).
 \Errors
 None.
 \SeeAlso
 \seep{InitVideo}, \seep{UpdateScreen}
 \end{procedure}
 
+\FPCexample{ex3}
+
 \begin{procedure}{DefaultErrorHandler}
 \Declaration
 function  DefaultErrorHandler(AErrorCode: Longint; AErrorInfo: Pointer): TErrorHandlerReturnValue; 
@@ -241,15 +266,6 @@ 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; 
@@ -258,66 +274,207 @@ procedure DoneVideo;
 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.
+\var{InitVideo} was called. Particularly, the \var{VideoBuf} and
+\var{OldVideoBuf} arrays are no longer valid after a call to 
+\var{DoneVideo}.
+
+The \var{DoneVideo} should always be called if \var{InitVideo} was called.
+Failing to do so may leave the screen in an unusable state after the program
+exits.
 \Errors
+Normally none. If the driver reports an error, this is done through the
+\var{ErrorCode} variable.
 \SeeAlso
+\seep{InitVideo}
 \end{procedure}
 
+For an example, see most other functions.
+
 \begin{function}{GetCapabilities}
 \Declaration
-function  GetCapabilities: Word; 
+function GetCapabilities: Word; 
 \Description
-{ Return the capabilities of the current environment }
+\var{GetCapabilities} returns the capabilities of the current driver.
+environment. It is an or-ed combination of the following constants:
+\begin{description}
+\item[cpUnderLine] The driver supports underlined characters.
+\item[cpBlink] The driver supports blinking characters.
+\item[cpColor] The driver supports colors.
+\item[cpChangeFont] The driver supports the setting of a screen font.
+Note, however, that a font setting API is not supported by the video unit.
+\item[cpChangeMode] The driver supports the setting of screen modes. 
+\item[cpChangeCursor] The driver supports changing the cursor shape.
+\end{description}
+Note that the video driver should not yet be initialized to use this
+function. It is a property of the driver.
 \Errors
+None.
 \SeeAlso
+\seef{GetCursorType}, \seep{GetVideoDriver}
 \end{function}
 
+\FPCexample{ex4}
+
 \begin{function}{GetCursorType}
 \Declaration
 function GetCursorType: Word; 
 \Description
-{ Return the cursor type: Hidden, UnderLine or Block }
+\var{GetCursorType} returns the current cursor type. It is one of the
+following values: 
+\begin{description}
+\item[crHidden] The cursor is currently hidden.
+\item[crUnderLine] The cursor is currently the underline character.
+\item[crBlock] The cursor is currently the block character.
+\item[crHalfBlock] The cursur is currently a block with height of half the
+character cell height.
+\end{description}
+Note that not all drivers support all types of cursors.
+\Errors
+None.
+\SeeAlso
+\seep{SetCursorType}, \seef{GetCapabilities}
+\end{function}
+
+\FPCexample{ex5}
+
+\begin{function}{GetLockScreenCount}
+\Declaration
+Function GetLockScreenCount : integer;
+\Description
+\var{GetLockScreenCount} returns the current lock level. When the lock
+level is zero, a call to \seep{UpdateScreen} will actually update the
+screen.
 \Errors
+None.
 \SeeAlso
+\seep{LockScreenUpdate}, \seep{UnlockScreenUpdate}, \seep{UpdateScreen}
 \end{function}
 
+\FPCexample{ex6}
+
+\begin{procedure}{GetVideoDriver}
+\Declaration
+Procedure GetVideoDriver (Var Driver : TVideoDriver);
+\Declaration
+\var{GetVideoDriver} retrieves the current videodriver and returns it in
+\var{Driver}. This can be used to chain video drivers.
+\Errors
+None.
+\SeeAlso
+\seef{SetVideoDriver}
+\end{procedure}
+
+For an example, see the section on writing a custom video driver.
+
 \begin{procedure}{GetVideoMode}
 \Declaration
 procedure GetVideoMode(var Mode: TVideoMode); 
 \Description
-{ Return dimensions of the current video mode }
+\var{GetVideoMode} returns the settings of the currently active video mode.
+The \var{row,col} fields indicate the dimensions of the current video mode,
+and \var{Color} is true if the current video supports colors.
 \Errors
+None.
 \SeeAlso
+\seef{SetVideoMode}, \seef{GetVideoModeData}
 \end{procedure}
 
+\FPCexample{ex7}
+
+\begin{function}{GetVideoModeCount}
+\Declaration
+Function GetVideoModeCount : Word;
+\Description
+\var{GetVideoModeCount} returns the number of video modes that the current
+driver supports. If the driver does not support switching of modes, then 1
+is returned.
+
+This function can be used in conjunction with the \seef{GetVideoModeData}
+function to retrieve data for the supported video modes.
+\Errors
+None.
+\SeeAlso
+\seef{GetVideoModeData}, \seep{GetVideoMode}
+\end{function}
+
+\FPCexample{ex8}
+
+\begin{function}{GetVideoModeData}
+\Declaration
+Function GetVideoModeData(Index : Word; Var Data: TVideoMode) : Boolean;  
+\Description
+\var{GetVideoModeData} returns the characteristics of the \var{Index}-th
+video mode in \var{Data}. \var{Index} is zero based, and has a maximum value of
+\var{GetVideoModeCount-1}. If the current driver does not support setting of
+modes (\var{GetVideoModeCount=1}) and \var{Index} is zero, the current mode 
+is returned.
+
+The function returns \var{True} if the mode data was retrieved succesfully,
+\var{False} otherwise.
+\Errors
+In case \var{Index} has a wrong value, \var{False} is returned.
+\SeeAlso
+\seef{GetVideoModeCount}, \seef{SetVideoMode}, \seep{GetVideoMode}
+\end{function}
+
+For an example, see \seef{GetVideoModeCount}.
+
 \begin{procedure}{InitVideo}
 \Declaration
 procedure InitVideo; 
 \Description
-{ Initializes the video subsystem }
+\var{InitVideo} Initializes the video subsystem. If the video system was
+already initialized, it does nothing. If the video subsystem was not
+initialized, it initializes the video subsystem. It initializes the video
+driver, and assigns the \var{VideoBuf} and \var{OldVideoBuf} pointers. After
+that, the screen is cleared.
 \Errors
+if the driver fails to initialize, the \var{ErrorCode} variable is set.
 \SeeAlso
+\seep{DoneVideo}
 \end{procedure}
 
-\begin{procedure}{RegisterVideoMode}
+For an example, see most other functions.
+
+\begin{procedure}{LockScreenUpdate}
 \Declaration
-procedure RegisterVideoMode(Col, Row: Word; Color: Boolean; VideoModeSelector: TVideoModeSelector; Params: Longint); 
+Procedure LockScreenUpdate;
 \Description
-{ Registers a video mode to be selectable by SetVideoMode } 
-{ moved to interface because we need a way to retrieve the modes }
+\var{LockScreenUpdate} increments the screen update lock count with one.
+As long as the screen update lock count is not zero, \seep{UpdateScreen}
+will not actually update the screen.
+
+This function can be used to optimize screen updating: If a lot of writing
+on the screen needs to be done (by possibly unknown functions), calling
+\var{LockScreenUpdate} before the drawing, and \seep{UnlockScreenUpdate}
+after the drawing, followed by a \seep{UpdateScreen} call, all writing will
+be shown on screen at once.
 \Errors
+None.
 \SeeAlso
+\seep{UpdateScreen}, \seep{UnlockScreenUpdate}, \seef{GetLockScreenCount}
 \end{procedure}
 
+For an example, see \seef{GetLockScreenCount}.
+
 \begin{procedure}{SetCursorPos}
 \Declaration
 procedure SetCursorPos(NewCursorX, NewCursorY: Word); 
 \Description
-{ Position the cursor to the given position }
+\var{SetCursorPos} positions the cursor on the given position: Column 
+\var{NewCursorX} and row \var{NewCursorY}. The origin of the screen is the
+upper left corner, and has coordinates \var{(0,0)}.
+
+The current position is stored in the \var{CursorX} and \var{CursorY}
+variables.
 \Errors
+None.
 \SeeAlso
+\seep{SetCursorType}
 \end{procedure}
 
+\FPCexample{ex2}
+
 \begin{procedure}{SetCursorType}
 \Declaration
 procedure SetCursorType(NewType: Word); 
@@ -337,9 +494,30 @@ None.
 \seep{SetCursorPos}
 \end{procedure}
 
-\begin{procedure}{SetVideoMode}
+\begin{function}{SetVideoDriver}
+\Declaration
+Function SetVideoDriver (Const Driver : TVideoDriver) : Boolean;
+\Description
+\var{SetVideoDriver} sets the videodriver to be used to \var{Driver}. If
+the current videodriver is initialized (after a call to \var{InitVideo})
+then it does nothing and returns \var{False}.
+
+A new driver can only be installed if the previous driver was not yet
+activated (i.e. before a call to \seep{InitVideo}) or after it was
+deactivated (i.e after a call to \var{DoneVideo}).
+
+For more information about installing a videodriver, see \sees{viddriver}.
+\Errors
+If the current driver is initialized, then \var{False} is returned.
+\SeeAlso
+\sees{viddriver}
+\end{function}
+
+For an example, see the section on writing a custom video driver.
+
+\begin{function}{SetVideoMode}
 \Declaration
-procedure SetVideoMode(Mode: TVideoMode); 
+Function SetVideoMode(Mode: TVideoMode) : Boolean;
 \Description
 \var{SetVideoMode} sets the video mode to the mode specified in \var{Mode}:
 \begin{verbatim}
@@ -350,16 +528,48 @@ procedure SetVideoMode(Mode: TVideoMode);
 \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}.
+\var{True}. 
+
+The function returns \var{True} if the mode was set succesfully, \var{False}
+otherwise.
+
 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.
+
+To know which modes are valid, use the \seef{GetVideoModeCount} and
+\seef{GetVideoModeData} functions. To retrieve the current video mode, 
+use the \seep{GetVideoMode} procedure.
 \Errors
 If the specified mode cannot be set, then \var{errVioNoSuchMode} may be set
 in \var{ErrorCode}
 \SeeAlso
+\seef{GetVideoModeCount}
+\seef{GetVideoModeData}
+\seep{GetVideoMode}
+\end{function}
+
+\begin{procedure}{UnlockScreenUpdate}
+\Declaration
+Procedure UnlockScreenUpdate;
+\Description
+\var{UnlockScreenUpdate} decrements the screen update lock count with one if
+it is larger than zero. When the lock count reaches zero, the 
+\seep{UpdateScreen} will actually update the screen. No screen upate will 
+be performed as long as the screen update lock count is nonzero. This 
+mechanism can be used to increase screen performance in case a lot of 
+writing is done. 
+
+It is important to make sure that each call to \seep{LockScreenUpdate} is
+matched by exactly one call to \var{UnlockScreenUpdate}
+\Errors
+None.
+\SeeAlso
+\seep{LockScreenUpdate}, \seef{GetLockScreenCount}, \seep{UpdateScreen}
 \end{procedure}
 
+For an example, see \seef{GetLockScreenCount}.
+
 \begin{procedure}{UpdateScreen}
 \Declaration
 procedure UpdateScreen(Force: Boolean); 
@@ -370,13 +580,17 @@ 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.
+wrote it to the screen (in the \var{OldVideoBuf} array). 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}
 
+For an example, see most other functions.
+
+\section{Writing a custom video driver}
+\label{se:viddriver}