mirror of
https://gitlab.com/freepascal.org/fpc/source.git
synced 2025-08-18 05:49:23 +02:00
+ Added examples
This commit is contained in:
michael
parent
754e4047a6
commit
eaa64ab4ce
314
docs/video.tex
314
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
|
||||
procedure SetVideoMode(Mode: TVideoMode);
|
||||
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
|
||||
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}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user