home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
pgraph2.zip
/
PGRAPH2.DOC
< prev
next >
Wrap
Text File
|
1996-11-24
|
22KB
|
581 lines
===================
P G R A P H 2
===================
documentation of fast full screen graphic library for OS/2
CONTENTS:
=========
I. Introduction
II. Input/output modes of VGA card
III. Using of the "Pixel" mode
IV. Tools for the text output
V. Animation Tools
VI. Description of types used in the library PGRAPH2
VII. Description of procedures and functions
VIII. Table of types
I. Introduction
^^^^^^^^^^^^^^^
PGRAPH2.DLL contains set of basic graphic functions and procedures for
fast graphic output. Library was created by Virtual Pascal compiler
(from fPRINT UK Limited) using C language calling convention - therefore
library can be used by "nonpascal" programmers.
Graphic output is realized directly through EGA/VGA ports and uses
several standard input/output modes for VGA card (640x480x16). Drawing of
basic graphic elements is realized by direct access to the video memory
(in DOS starting at address $A000:$0000).
PGRAPH2.DLL was created according to the following concept:
1) To achieve as high speed of graphic output, as possible - at the cost
of less universal graphic tools.
2) To create necessary graphic tools for "science" and "technical" purposes -
- not for games and so on.
3) To create necessary tools for text input/output under VGA graphic mode.
II. Input/output modes of VGA card
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Input/output mode of VGA can be adjusted by setting of certain values at
VGA ports. PGRAPH2.DLL uses the following modes:
1) "Putpixel" mode, that is realized by procedure PutPixel. This procedure
is very slow - at each time, the x coordinate, y coordinate and color
of pixel must be specified.
2) "Pixel" mode, that is switched by procedures PixelMode_On and
PixelMode_Off. When "Pixel" mode is switched on, a pixel at the screen
can be drawn (in the previously selected foreground color and writemode)
by direct access to the video memory. This process is fast and it is used
for lines drawing.
3) "Line" mode, that is switched by procedures LineMode_On and LineMode_Off.
In this mode, eight pixels (one byte) can be drawn at once by direct
access to the video memory - position corresponding to "one" in the byte
is drawn by the foreground color, position corresponding to "zero" in the
byte is drawn by the background color. This process is the fastest and
is used for filling and text drawing.
III. Using of the "Pixel" mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"Pixel" mode is supposed for the following procedures:
Pixel - pixel
Vline - vertical line
Hline - horizontal line
Line - line
LineTo - line from current position
Sym0 - centered small rectangle
CesLText - scalable line text
Procedures Pixel and Sym0 must use the following programming scheme:
...
<SetColor(f);> - set foreground color
<SetWriteMode(w);> - set write mode (AND, XOR, ...)
PixelMode_On; - switch "Pixel" mode on
<set of Pixel or Sym0 calling> - draw pixels or symbols
PixelMode_Off; - switch "Pixel" mode off
...
For other procedures, the following scheme is recommended:
...
<SetColor(f);> - set foreground color
<SetWriteMode(w);> - set write mode (AND, XOR, ...)
pxm:=false; - switch off internal "Pixel" mode switching
PixelMode_On; - switch "Pixel" mode on
<set of procedure(s) calling> - draw lines or text
PixelMode_Off; - switch "Pixel" mode off
pxm:=true; - switch on internal "Pixel" mode switching
...
It is faster, than the following scheme:
...
<SetColor(f);> - set foreground color
<SetWriteMode(w);> - set write mode (AND, XOR, ...)
<set of procedure(s) calling> - draw lines or text
...
Recommended scheme minimizes accessing of VGA ports - it is important
especially for multitasking operating systems.
In the "Pixel" mode, calling of the SetColor and SetWriteMode procedures
must be followed by calling of the PixelMode_On procedure to take effect.
The "Pixel" mode is only mode, that accepts the effect of the SetWriteMode
procedure.
IV. Tools for the text output
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
PGRAPH2 contains procedures such as GotoXYG, WriteG, WriteGn and ClrEolG,
which enables to simulate text output in like manner, as Pascal's CRT unit
does.
There are functions GetWHX and GetWHY, which return current coordinates of
cursor during text output. GetWHX and GetWHY have similar function as
a WHEREX and WHEREY in the CRT unit of Turbo/Borland Pascal. This type of
text output uses fonts of various height (14,16 and 24 pixels) and constant
width (8 pixels). Fonts are constructed by the same way as a standard VGA
(EGA) text fonts.
V. Animation Tools
^^^^^^^^^^^^^^^^^^
There is simple animation tool in the library PGRAPH2 based on saving and
restoring certain background area. Procedure GetArea saves rectangular
area of background and procedure PutArea restores it. Amount of memory
needed for saving computes function AreaSize.
Rectangular area is automatically byte aligned in the x direction
to speed up saving and restoring process.
Animation should be programmed according to the following scheme:
...
i:=0;
save area 0;
draw animated picture at area 0;
repeat
restore area i;
save area i+1;
draw animated picture at area i+1;
i:=i+1;
until end condition;
...
Using of the animation tools is demonstrated in the last screen of
DEMOPG.EXE.
VI. Description of types used in the library PGRAPH2
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are only two special types used in the library PGRAPH2:
■ S127 = string[127] ... string type used in certain procedures (see
'Description of procedures and functions').
This type uses 'Pascal' string, that means,
string is zero-based array of characters
starting at element with index one and element
with index zero contains length of string.
■ POINTTYPE = record x,y:integer end ... type of graphic point used in the
FillPolygon procedure.
VII. Description of procedures and functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This section describes procedures and functions available in the library
PGRAPH2. Procedures and functions compatible with Borland Pascal GRAPH unit
are marked by *.
■ function KeyPressed:boolean;
------------------------------
Returns true, if any key on the keyboard was pressed. Otherwise returns
false.
■ function ReadKey:char;
------------------------
Returns ASCII code of pressed key on the keyboard. If functional key is
pressed (Alt+K, F1, Shift+F2, ....), the ReadKey returns 0 and next
calling of the ReadKey returns non zero code.
■ PlaySound(Freq, duration:longint);
------------------------------------
Plays sound using internal speaker. Duration is time in milliseconds.
■ procedure SetLIWI(LiWi:byte);
-------------------------------
Sets width of lines, value of LiWi has to be in the range <1,2,3>.
Affects lines drawn by Line, HLine, Vline, LineTo, Rectangle, Triangle,
Ellipse and CesLText.
Default value: LIWI = 1.
■ procedure SetDOT(Dot:boolean);
--------------------------------
If Dot is true, lines are drawn as a dotted lines.
Affects lines drawn by Line, HLine, Vline, LineTo, Rectangle, Triangle,
Ellipse and CesLText.
Default value: DOT = false.
■ procedure SetPXM(PXM:boolean);
--------------------------------
If PXM is false, internal "Pixel" mode switching in certain procedures
is switched off - see section 'Using of the "Pixel" mode' above.
Default value: PXM = true.
■ procedure SetRST(RST:word);
-----------------------------
RST contains raster definition for figure filling. Filling is performed
in the "Line" mode using horizontal lines - upper and lower bytes of the RST
are exchanged before each new horizontal line output.
In the DEMOPG.EXE, the RST is set to $AA55.
Default value: RST = $FFFF.
■ function GetWHX:byte;
-----------------------
Returns x coordinate of text cursor in the range 1 <= WHX <= 80.
The same function, as a WHEREX in the standard Pascal's unit CRT.
Default value: WHX = 1
■ function GetWHY:byte;
-----------------------
Returns y coordinate of text cursor in the range 1 <= WHX <= NTEXTROW.
The same function, as a WHEREY in the standard Pascal's unit CRT.
Default value: WHY = 1
■ function GetTEXTROW:byte;
---------------------------
Returns maximal text rows, which can be used with respect to the text size.
See description of GrafFont procedure below.
■ function GetCRX:integer;
--------------------------
Returns x coordinate CRX of the cross used in the MoveCross procedure in the
range 0 <= CRX <= 639.
Default value: CRX = 320
■ function GetCRY:integer;
--------------------------
Returns y coordinate CRY of the cross used in the MoveCross procedure in the
range 0 <= CRY <= 479.
Default value: CRY = 240
■ procedure SetCRS(CRS:byte);
-----------------------------
Sets speed of cross moving used in the MoveCross procedure in the range
1 <= CRS <= 5.
Default value: CRS = 2
■ function GetFKL:boolean;
--------------------------
Returns value of variable FKL. This variable is used in the function Klic
and indicates (if true), the function key (such as F1, Alt+P, Shift+F9, ...)
was pressed.
■ function GetShi:byte;
-----------------------
Returns value of variable SHI. This variable is used in the function Klic and
indicates whether Shift, Ctrl or Alt key was pressed (see below).
■ procedure SetINS(INS:byte);
-----------------------------
Sets value of variable INS to switch between insert mode (INS=1) and replace
mode (INS=0). Used in the Editg procedure.
■ function Klic: char;
-----------------------
Returns a key pressed on the keyboard.
Sets FKL variable to true, if functional key (F1, Alt+C, ...) was pressed.
Sets SHI variable to: 2 ... if Shift key was pressed
4 ... if Ctrl key was pressed
8 ... if Alt key was pressed
■ procedure Editg(x1,x2,y:byte; var st:s127);
---------------------------------------------
Enables to edit string at row y, in the column range x1,x2.
Intended for graph mode and uses graphic cursor (see description
of Cursor procedure below).
1 <= x1 < x2 <= 80, 1 <= y <= NTEXTROW
■ procedure Num(x,y:byte; var n; t:char; k,l:integer);
------------------------------------------------------
Enables to edit and enter number, starting at text position x,y
n is untyped variable containing number
t is type of n: "b" ... byte "s" ... single
"i" ... integer "r" ... real
"w" ... word "d" ... double
"l" ... longint "e" ... extended
"h" ... shortint
k is total number of digits
l is number of decimal digits
■ procedure WriteNum(var n; t:char; k,l:integer);
-------------------------------------------------
Enables to write number at text position WHX,WHY
n is untyped variable containing number
t is type of n: "b" ... byte "s" ... single
"i" ... integer "r" ... real
"w" ... word "d" ... double
"l" ... longint "e" ... extended
"h" ... shortint
k is total number of digits
l is number of decimal digits
■ function GraphInit(s:s127):integer;
------------------------------
Initializes standard VGA graph mode (640x480x16).
s is path to the directory containing font files (CSA14.FNT, CSA16.FNT,
CSA24.FNT, ZNC0 and ZNC1).
Returns error code as an integer value:
0 ... Without error
1 ... Wrong path to the font files
2 ... Cannot access video screen selector
3 ... VGA display required
■ procedure Lock_On;
--------------------
Disables to press task switching keys. Unfortunately, system OS/2 hangs
for 30 seconds, if task switching key is pressed.
■ procedure Lock_Off;
---------------------
Enables to press task switching keys - default. Task switching keys may
be pressed only if there is no graphic output (that is, VGA ports are
not accessed), otherwise system OS/2 hangs.
■ function SetGraphMode:integer;
--------------------------------
Restores graph mode from text mode.
Returns error code as an integer value:
0 ... Without error
3 ... VGA display required
■ procedure RestoreCrtMode;
---------------------------
* Switches to the text mode.
■ procedure ClearDevice;
------------------------
* Clears graphic screen (fills screen with background color).
■ procedure SetColor(color:word);
---------------------------------
* Sets foreground color in range <0,15>.
■ procedure BackColor(color:word);
----------------------------------
Sets background color in range <0,15>.
■ procedure FBC(fcolor,bcolor:word);
------------------------------------
Sets foreground and background color.
■ function GetColor:word;
--------------------------
* Returns current foreground color.
■ procedure SetWriteMode(mode:integer);
---------------------------------------
* Sets mode for drawing in the "Pixel" mode.
0 = NormalPut, 1 = XORPut, ....
■ procedure SetRGBPalette(color,red,green,blue:integer);
--------------------------------------------------------
* Sets RGB values (in range <0,63>) for specified color (in range <0,15>).
■ function GetPixel(x,y:integer):word;
---------------------------------------
* Returns pixel color at specified coordinates x,y.
■ procedure PutPixel(x,y:integer; color:word);
---------------------------------------------
* Draws a pixel with specified color at specified coordinates x,y.
■ procedure Pixel(x,y:integer);
-------------------------------
Draws a pixel with color specified by SetColor procedure at specified
coordinates x,y. Much faster, than PutPixel.
Accepts setting of SetWriteMode and foreground color.
Must be in the "Pixel" mode.
■ procedure PixelMode_On;
-------------------------
Switches on "Pixel" mode. See 'Using of the "Pixel" mode' above.
■ procedure PixelMode_Off;
--------------------------
Switches off "Pixel" mode. See 'Using of the "Pixel" mode' above.
■ procedure LineMode_On;
------------------------
Switches on "Line" mode. See 'Input/output modes of VGA card' above.
■ procedure LineMode_Off;
-------------------------
Switches off "Line" mode. See 'Input/output modes of VGA card' above.
■ procedure Vline(x,y1,y2:integer);
-----------------------------------
Draws a vertical line. Accepts setting of LIWI, DOT, SetWriteMode
and foreground color.
■ procedure Hline(x1,x2,y:integer);
-----------------------------------
Draws a horizontal line. Accepts setting of LIWI, DOT, SetWriteMode
and foreground color.
■ procedure Line(x1,y1,x2,y2:integer);
--------------------------------------
* Draws a line. Accepts setting of LIWI, DOT, SetWriteMode and foreground
color.
■ procedure MoveTo(x,y:integer);
--------------------------------
* Moves current graphic pointer to coordinates x,y.
■ procedure LineTo(x,y:integer);
--------------------------------
* Draws a line from the current pointer to coordinates x,y.
Accepts setting of LIWI, DOT, SetWriteMode and foreground color.
■ procedure Sym0(x,y:integer);
------------------------------
Draws a little square centered at coordinates x,y.
Accepts SetWriteMode and foreground color.
Must be in the "Pixel" mode.
■ procedure Rectangle(x1,y1,x2,y2:integer);
-------------------------------------------
* Draws a rectangle - x1,y1 are coordinates of the upper left corner,
x2,y2 are coordinates of the lower right corner.
Accepts setting of LIWI, DOT, SetWriteMode and foreground color.
■ procedure FillRectangle(x1,y1,x2,y2:integer);
-----------------------------------------------
Fills a rectangle - x1,y1 are coordinates of the upper left corner,
x2,y2 are coordinates of the lower right corner.
Accepts setting of RST variable, foreground and background color.
■ procedure Triangle(x1,y1,x2,y2,x3,y3:integer);
------------------------------------------------
Draws a triangle - x1,y1, x2,x3 and x3,y3 are coordinates of corners.
Accepts setting of LIWI, DOT, SetWriteMode and foreground color.
■ procedure FillTriangle(p1,q1,p2,q2,p3,q3:integer);
----------------------------------------------------
Fills a triangle - x1,y1, x2,x3 and x3,y3 are coordinates of corners.
Accepts setting of RST variable, foreground and background color.
■ procedure Ellipse(xc,yc:integer; xrad,yrad:integer);
------------------------------------------------------
Draws an ellipse - xc,yc is the center point; xrad,yrad are radii.
Accepts setting of LIWI, DOT, SetWriteMode and foreground color.
■ procedure FillEllipse(xc,yc:integer; xrad,yrad:integer);
----------------------------------------------------------
Fills an ellipse - xc,yc is the center point; xrad,yrad are radii.
Accepts setting of RST variable, foreground and background color.
■ procedure FillPolygon(n: integer; var p);
-------------------------------------------
Fills a polygon - p is array of POINTTYPE (vertices of polygon) and
n is number of vertices. The last vertex must be equal to the first.
Accepts setting of RST variable, foreground and background color.
■ function AreaSize(x1,y1,x2,y2:integer):longint;
--------------------------------------------------
Returns amount of the memory needed for saving rectangular area
by GetArea procedure.
You must ensure, that 0 <= x1 < x2 <= 639 and 0 <= y1 < y2 <= 479.
■ procedure GetArea(x1,y1,x2,y2:integer; var b);
------------------------------------------------
Saves rectangular area of graphic screen into buffer b. Size of
the buffer would be specified by the AreaSize function. Similar
to the GetImage procedure in Borland Pascal GRAPH unit, but
x-range of the area is automatically byte aligned (from speed reasons).
You must ensure, that 0 <= x1 < x2 <= 639 and 0 <= y1 < y2 <= 479.
■ procedure PutArea(x1,y1:integer; var b);
------------------------------------------
Restores rectangular graphic area contained in the buffer b.
Similar to the PutImage procedure in Borland Pascal GRAPH unit, but
x-range of the area is automatically byte aligned (from speed reasons).
■ procedure MoveCross(ch:char; fkl:boolean);
--------------------------------------------------
Draws and moves a little cross around the screen using arrow keys
and SetWriteMode(1). Keys 1,2,3,4 and 5 can be used to change movement
speed. Calling MoveCross(0,false) should be used for the first drawing
of the cross or for it's disappearance.
■ procedure GrafFont(r:byte);
-----------------------------
Reads font for WriteG, WriteGn and CesTextC procedures. Size of
the font is 8 x r, where r (font height) is 14,16 or 24.
■ procedure CesTextC(x,y:integer; s:s127; d:boolean);
-----------------------------------------------------
Draws text using PutPixel procedure. If d is true, the text is
written horizontally, otherwise the text is written vertically.
Accepts foreground and background color.
■ procedure ClrEolG;
--------------------
Clears text from the current position of WHX,WHY to the end of line.
The same function as a ClrEol in the standard Pascal text mode.
■ procedure GotoXYG(x,y:byte);
------------------------------
Sets position of WHX,WHY to the coordinates x,y in the range
1 <= x <= 80, 1 <= y <= NTEXTROW.
■ procedure WriteG(s:s127);
---------------------------
Draws string s at current position WHX,WHY. Very fast, uses "Line" mode.
Accepts foreground and background color.
■ procedure WriteGn(s:s127);
----------------------------
Draws string s at current position WHX,WHY and skips to the first column
of the next row. Very fast, uses "Line" mode.
Accepts foreground and background color.
■ procedure LineFont(l:byte);
-----------------------------
Reads scalable line font for CesLText procedure.
l is size of font in the range <0,1>.
■ procedure CesLText(x,y:integer; s:s127; zv:single; d:boolean);
----------------------------------------------------------------
Draws string s starting at coordinates x,y using line font -
zv is scale (using whole numbers is recommended) and
d is direction (true - horizontal drawing, false - vertical drawing).
Accepts setting of LIWI, DOT, SetWriteMode and foreground color.
VIII. Table of types
^^^^^^^^^^^^^^^^^^^^
Following table should be helpful for "nonpascal" programmers.
1) Ordinal types
----------------
Pascal │
type │ format │ range
═════════╪═════════════════╪══════════════════════════
boolean │ unsigned 8-bit │ 1 (true) or 0 (false)
byte │ unsigned 8-bit │ 0 .. 255
shortint │ signed 8-bit │ -128 .. 127
word │ unsigned 16-bit │ 0 .. 65535
integer │ signed 16-bit │ -32768 .. 32767
longint │ signed 32-bit │ -2147483648 .. 2147483647
2) Real types
-------------
Pascal │
type │ Range │ Digits │ Bytes
═════════╪═════════════════════╪════════╪══════
real │ 2.9e-39..1.7e38 │ 11-12 │ 6
single │ 1.5e-45..3.4e38 │ 7-8 │ 4
double │ 5.0e-324..1.7e308 │ 15-16 │ 8
extended │ 3.4e-4932..1.1e4932 │ 19-20 │ 10
comp │ -9.2e18..9.2e18 │ 19-20 │ 8
--
-- End of document file --
--