ђјјј ђјјѓ ђјјѓ ђјјј ђ ђ
ђ ѓ ђѓѓ ђѓѓђ ђѓ ѓјјѓ
јјјј ј ј ј ј ј ј ј *************************************************
******************************* (c) 1996-1998 by Stefan Goehler, Germany ***
***** GRAFX 1.3c ************************************************************
***** Documentation - Version 1 *****
**** Find me in the Web @ http://sourcenet.home.pages.de ***
*** Mail me @ stefan.goehler@gmx.de *
** *
* *
* Thanx fly to Dmitri Chaloupov for doing some corrections on my spelling :) *
* Also Hristo Chilingirov should be mentioned - he reprogrammed the *
* hardware acceleration for Cirrus cards - he had IMHO a good *
* documentation, the cirrus-unit seems to run very well. *
* Another thanx flies to Christian Klukas - he made a lot of testing on *
* version 1.3. Only with his help I was able to make the newest *
* release 1.3 so stable and bugfree (hey ;)! *
****** *
******************************************************************************
***
*
Hi!
Well, it's almost time to make this readme - we've got already version 1.3!
Some release notes: This new version makes use of the S3 and Cirrus
hardware accelerated functions. On these cards, UNIVBE _won't_ speed up
the card in any way. In this case UNIVBE is only wasted memory! There may
be some incompatibilities with such cards.
There's a procedure to control this: SetAccelerationMode(Mode : byte)
Following numbers you can use as mode:
0 : NO acceleration - use ONLY VESA
1 : Use speedups like scrolling, bankswitching
2 : Use ALL supported HW-accelerations (default)
The best way is, you call this procedure BEFORE you use set256mode.
Of course you can change also the acceleration mode by runtime,
but you should use this only for changes by the user of your
software by runtime.
Now all the procedures provided by Grafx have a short description...
I'll revise this text also into html in the next time (I think
with Grafx2).
BTW, the manual is not finished. I began making it with version
1.3a1 or so, where were not all procedures. Don't blame me, I'm
happy I finally finished version 1.3 (final version) after a
period of a half year [grin].
shortcuts : i.e. = in example
>> procedure getpal;
Get the whole palette and put the colors into the variable pal.
>> procedure setpal;
Set the whole palette provided by the variable pal.
>> procedure shiftpal;
Shift the virtual palette values right by two bits. This is needed
when the pal-variable contains 8bit color values (i.e. if you have
put there a pcx-color table). It shifts the color values to 6bit
(normal VGA).
>> procedure getuserpal(var pal);
Same as getpal, but you can give your own colortable as a parameter.
>> procedure setuserpal(var pal);
Same as setpal but you can give your own colortable as a parameter.
>> procedure setrgbpalette(colornum,redvalue,greenvalue,bluevalue : integer);
Set a color directly. Colornum contains the color number, R,G and B contain
the color values (remember: only 6 bits are used - that means nothing
larger than 63 !)
>> procedure getrgbpalette(color : byte;var r,g,b : byte);
Get the colors of palette index COLOR into the variables R,G and B.
>> procedure setrgbpal(i,r,g,b : byte);
>> procedure getrgbpal(i : byte;var r,g,b : byte);
These 2 procedures run like their pendants with the 'ette' on the end
but it does not affect the real color palette but the virtual color
palette which is in the variable PAL.
>> function findnearcol(nr,ng,nb : byte) : byte;
Looks for the nearest rgb-value available. You should call getpal
prior to this function, to get to use the actual palette.
>> procedure loadjascpal(path : string);
Load a palette made with Paint Shop Pro. The palette is loaded into the
virtual palette. To set the palette you should use setpal thereafter.
>> function loadpal(name : string;pal : pointer) : boolean;
Load a 768-byte-sized palette into pal^. To set the palette, loaded by
this function, use setuserpal.
>> procedure getvesamodeinfo;
This function is only useful if you made a 15/16/24/32-Bit-mode unit,
which needs the vesa mode information. The whole variable VESAMODEINFO
in the unit gr_vars will be filled.
>> procedure set256mode(mode : integer);
Set the computer into graphical mode. Use the following values
to set a mode:
0 : 320x 200
1 : 640x 400
2 : 640x 480
3 : 800x 600
4 : 1024x 768
5 : 1280x1024
6 : 1600x1200
After you called this procedure, you should call graphresult to check
if there were any errors in the initialization. Otherwise your program
may crash when there was a problem ;))).
This is not the best way to initialize a graphical mode. Grafx2 will
have a syntax like this: setmode(640,480,8);
>> function grapherrormsg(errorcode : integer) : string;
Use it with the errorcodes returned by graphresult - you'll get back
an error string.
>> function graphresult : integer;
Graphresult will be always equal 0 if there were no errors after a
call of a procedure (like set256mode, loadfont etc). If it returns
nonzero, then use GraphErrorMSG with the returned value to give
out the errorstring.
>> function getdrivername : string;
Returns string with the name of detected card. If a special card is
supported (like S3 and Cirrus) then it returns the chip
information, like 'S3 Trio64 764' otherwise only 'VESA'.
>> function getmaxmode: integer;
Returns the number of the maximum resolution mode available. Doesn't
work at all at the moment. This function will be not needed any
more in Grafx2 - there you have a large variable with all available
graphical modes.
>> procedure closegraph;
You _must_ use this to close a graphical mode. It restores the last
textmode and restores the last text screen. It also sets a variable,
defining that you are not in graphical mode anymore.
>> procedure waitretrace;
Avoids flickering in animations, because it pauses drawing until the
vertical beam of the monitor goes back to start (top left point on
screen). Use it when finished one frame before drawing the next.
>> procedure hretrace;
Waits until the cathode-beam is in the next line. Useful for
copperbars.
>> procedure setscreen(on : boolean);
Sets the screen on(true) or off(false). If it's set to off,
the memory-transferring process gets a little more speed and you can
draw slow things(like loading a png-picture) while the user can'n see
the process on the monitor.
>> procedure setviewport(x1,y1,x2,y2 : integer;clip : boolean);
Sets the actual viewport. Clip means that the draw commands can draw
only in the ranges of rectangle (x1,y1),(x2,y2).
>> procedure getviewsettings(var viewport : viewporttype);
Get the actual viewport settings.
>> procedure clearviewport;
Clear the actual viewport area.
>> procedure getimagesize(p : pointer;var x,y : word);
Get the sizes of an image captured with getimage or set by setimagesize
in memory.
>> procedure setimagesize(p : pointer;x,y : word);
Set the sizes of an image in memory.
If you wanna use your self-made images (i.e. they're calculated in
memory), use this function. Please use the variable
ImageDataSize to get the size of this sizedata. At the moment,
the datasize is 4, but it'll change in further versions because
of the support of Hi/Truecolor. Then the i.e. 2 bytes more are
used the specify the colordepth, alphamapping-information,
and maybe for 256 color-images if there's any palette at the
end of an image (because it's needed in truecolor...)
>> function imagesize(x1,y1,x2,y2 : word) : word;
Returns memory size needed for an image with coordinates
(x1,y1),(x2,y2).
It returns zero and graphresult <> 0 if the image is too large.
>> procedure scale(image : pointer;px,py,sx,sy : word);
Scale image on position PX:PY with the factors SX and SY.
>> procedure putpixel(x,y :word;color : byte);
Put a pixel with COLOR at position X:Y.
>> function getpixel(x,y :word) : byte;
Get the pixel color at position X:Y.
>> procedure putimage(x,y: integer;p : pointer);
Put image from memory pointer P, previosly captured with getimage or
set by setimagesize, at position X:Y.
>> procedure putsprite(x,y: integer;p : pointer;key : byte);
Runs almost like putimage with the difference that you can declare any
color as transparent through variable KEY.
>> procedure getimage(x,y,x2,y2 : integer;p : pointer);
Save an image starting at X:Y and ending at X2:Y2 to the pointer P.
You can calculate the size of P with imagesize(x,y,x2,y2) or with the
following calculation : abs(x2-x)*abs(y2-y)+4 (the 4 extra bytes are
used to save the size of the image).
>> procedure bar(x1,y1,x2,y2: integer);
Draw a filled rectangle starting from X1:Y1 and ending at X2:Y2. The
filling pattern and the color can be set via setfillstyle. To set
only the color of bar, use setfillcolor.
>> procedure line(x1,y1,x2,y2: integer);
Draw a line starting from X1:Y1 and ending at X2:Y2. To set the color
of line call setcolor before drawing line.
The fastest way to draw horizontal lines is hline.
The fastest way to draw vertical lines is vline.
>> procedure bitblit(x1,y1,x2,y2,dstx,dsty : integer);
Copy the rectangle X1:Y1-X2:Y2 to the position DSTX:DSTY. Remember that
this function is very fast with supported gfx-cards, because it uses
hardware acceleration.
>> procedure rbar(x1,y1,x2,y2 :integer;r:word);
Similar to bar, but draws rounded edges, using radius R. Looks sometimes
very nice ;)
>> procedure fillcircle(x,y :integer;r:word);
Draw a filled circle. Center is defined by X:Y, radius is R. Filling
pattern and color can be set via setfillstyle. To set only the color,
use setfillcolor.
>> procedure circle(px,py :integer;r:word);
Draws a circle. Center is defined by PX:PY, radius is R. Color can be
set via setcolor.
>> procedure hline(x1,y1,sizex: integer;col : byte);
Draw a horizontal line with the color COL with the length SIZEX from
position X1:Y1.
>> procedure vline(x1,y1,sizey: integer;col : byte);
Draw a vertical line with the color COL with the length SIZEY from
position X1:Y1.
>> procedure putline(x1,y1,sizex: integer;p : pointer);
Put a line with the imagedata P and size SIZEX on the screen, starting
at point X1:Y1.
>> procedure spriteline(x1,y1,sizex: integer;p : pointer;key : byte);
Put a line with the imagedata P and size SIZEX on the screen,
starting at point X1:Y1. KEY defines the transparent color.
>> procedure getline(x1,y1,sizex: integer;p : pointer);
Get a line from the screen to the pointer P in memory with the length
SIZEX starting from point X1:Y1.
>> procedure fillpoly(numpoints : integer;var points : array of pointtype);
Draw a filled polygon. Use just like the one in Graph.TPU by Borland.
>> procedure drawpoly(numpoints : integer;var polypoints : array of pointtype);
Draw a boundary polygon. Use just like the one in Graph.TPU by Borland.
>> procedure rectangle(x1,y1,x2,y2: integer);
Draw a boundary rectangle. Set the color via setcolor.
>> procedure rrectangle(x1,y1,x2,y2 :integer;r : word);
Draw a boundary rectangle with rounded edges. The radius is R.
Set the color via setcolor.
>> procedure cleardevice;
Clear the whole screen.
>> procedure floodfill(x,y : integer;border : byte);
Fill an area starting at point X:Y. The color of the border (= the color
where the filling stops) is BORDER. Set the filling color and pattern
via setfillpattern. To set only the color use setfillcolor.
>> procedure settextjustify(Horiz, Vert: Word);
Set text justification. Use just like the one in Graph.TPU by
Borland.
>> procedure readgraphline(x1,y1,col,maxchars,posx : word;var s2 : string);
Read a line from the screen at position X1:Y1. The text color is COL.
MAXCHARS means the maximum number of chars to read. POSX is the
starting position of the cursor in the string. It should be = 1 for the
first char, that means zero is not allowed! S2 contains the output
string, it can be empty at the beginning, but it can also have
chars in it - these chars would be drawn on screen and you can edit
them with the string then.
>> procedure writexy(x,y : integer;s : string);
Write the string S at position X:Y. Set color of the text via setcolor.
>> procedure outtextxy(x,y : integer;s : string);
Same as writexy. Use just like the one in Graph.TPU by Borland.
This is only for compatibility with graph.
>> procedure setfont(fnt,size : byte);
Set a font. FNT represents the selected font:
0 = Standard font
2 = Small font
^^both automatically linked with graph-unit. All other fonts loadable
by the user, but only one vectorfont at a time (at the moment).
SIZE is the size of the font. Will only affect vector fonts (also
at the moment).
>> function makestr(w : longint) : string;
Convert an integer value to a string. Useful with writexy.
>> function makestrr(r : real;sh,st : byte) : string;
Convert a real to a string. Useful with writexy.
R is converted like following: R:SH:ST.
To get 2 values after the comma, use it like this:
s := makestrr(r,4,2); Write(s);
That result will be the same as if you did: Write(r:4:2);.
>> function textwidth(s : string) : word;
Get the width of the textstring S for the currently used font.
>> function textheight : word;
Get the height of the character for the currently used font.
>> function loadfont(name : string;num : byte) : boolean;
Load a font from disk. NUM is the handle which is used to select font
later in the program. It must be above 2!
>> function loadfontmem(p : pointer;num : byte) : boolean;
The same as loadfont, but it loads the font from the memory. Useful for
linked-in fonts.
>> procedure setactivepage(page : byte);
Set the graphical page, you want to draw at. The first page
(default on start) is 0. Does not means that it is visible to user.
>> procedure setvisualpage(page : word);
Set graphical page, which the user can see. This procedure
automatically avoids flickering (for smooth animations).
>> procedure scroll(ypos : word);
Set the y-start of the screen. Default (on start) is 0.
>> procedure setcolor(col : byte);
Set the current paint color.
>> function getcolor : byte;
Get the current paint color.
>> procedure setfillstyle(pattern : word;col : byte);
Use just like the one in Graph.TPU by Borland.
>> procedure setfillcolor(col: byte);
Sets only the filling color. Pattern won't change.
>> function getmaxx : word;
Gives back the maximum X - resolution of the screen.
Only for compatibility - use variable maxx instead
>> function getmaxy : word;
Gives back the maximum Y - resolution of the screen.
Only for compatibility - use variable maxy instead
>> function getmaxcolor : word;
Gives back the number of available colors. It's always 256 at the
moment.
>> procedure setwritemode(writemode: integer);
Is almost the same like in the unit graph, but affects only the
procedure line and there's only the xorput and the normalput mode
available (at the moment).
That's all at the moment. Improvements'll come soon (Well, I hope so ;).
Known bugs
. Univbe and other Utilities may make problems (not MY problem ;)
. older S3-cards may make some problems (some have also a
hardware-bug in their bitblitting-engine) - thanx fly
to S3 because they did not response any questions about
documentation (I tried it about 5 times!!)
. very late S3-cards won't work in acceleration mode 2 - it seems that
S3 changed some registers... :(
****** COMING SOON ***********************************************************
Well, the next Version should be Grafx2. It'll support Hi/Truecolor.
First versions (only standalone for Hi/True yet) are available for
interested persons. The initializing of a graphical mode will be
much more clear and simple than the current:
setmode(640,480,8)
instead of set256mode(2) - you know exactly what you initialize
and you are able to use then also non-standard-modes 320x512
I'll also write some other new units:
. jpeg-support (yes, I have it already! NO empty pretention)
. maybe gif-support (also anigifs)
. also maybe a support for FLC-Files
. truetype-support (will use freetype 1.0, also with fontsmoothing!!)
Grafx2 won't be that compatible to Grafx1.3. It could be that
you have to rewrite your programs (but in most case, you will
only have to replace some commands I think)
I don't know yet, but I think about a FPK-Pascal port of my unit.
But before I do this, I have to finish Grafx2. Also this depends
on if FPK-Pas finally gets it's own fully integreated Dos-IDE with
syntax colors, undo... like the TP-IDE.
Wanna know more about me?
Well,
my name is Stefan Goehler. I'm living in Germany near Rostock. I have brown
hair and (dark-)brown eyes. I've reached in my 17 years of living here on
this silly world a size of 1.71m.... that's enough... I'm too lazy to think
about what I could write any more... ;)
Bye,
Stefan/NooN/Skywalker (I am only ONE person ;)
******************************************************************************
| 
Stefan Goehler