                   X-Mode Library for Turbo Pascal and TASM
                                 Version 1.2

                              THE FINAL RELEASE

                        Code written by Antti Virtanen
                       Documents written by Tapio ijl

                      Copyright (C) Napalm Software 1994.
                             All rights reserved.

            ͻ
                                                           
                      Member of                           
                       Suomen (Finnish)                    
                Peliohjelmoijat (Game Programmers)  
                            ::::::::::::::::::::::::::::::::::  
                                                                
            ͼ


TABLE OF CONTENTS

1.0 Introduction

       1.1 License agreement and disclaimer
       1.2 What is X-Mode Library for TP and TASM
       1.3 Hardware and software requirements
       1.4 Example programs and important notices
       1.5 Release history of XLIBTP
       1.6 What is Napalm Software
       1.7 How you can contact to the authors
       
2.0 Installing XLIBTP

       2.1 Distribution package
       2.2 Installing XLIBTP
       2.3 Ready to use XLIBTP

3.0 Reference guide

       3.1 How to use reference guide
       3.2 Variables, consts and types
       3.3 Data formats

4.0 Tips and tricks

       4.1 Palette routines
       4.2 Split screen

5.0 Utilities included to XLIBTP

       5.1 IDF2ICF.EXE
       5.2 TPU2INT.EXE
       5.3 MOUSE.TPU (For TP 7.0 and above)

6.0 Assembler part of XLIBTP

       6.1 What is tweaked-mode
       6.2 How to use assembler sources

7.0 Special info about programming vga

       7.1 Virtual screen
       7.2 How vga uses it's 256 Kb video mem in the tweaked or/and xmode
       7.3 Write mode 1
       7.4 640 x 400 xmode
       7.5 Vertical resolution
       7.6 Horizontal resolution
       7.7 Xmode games
       7.8 Filling style

8.0 It's time to end

       8.1 Last words
       8.2 Greetings, credits and thanks to
       8.3 Special to artists


1.0 Introduction

1.1 License agreement and disclaimer


       This software is distributed as a freeware. That means that it's
       copyrighted by the author (Napalm Software), but you may use it as you
       want to. But NO modifications allowed without written permission of the
       author. And no fee can be taken for distributing it. All information
       herein is presented "as-is". You use this product at your own risk. No
       warranties of compability etc. are given. And: USING IN COMMERCIAL
       PRODUCTS WITHOUT WRITTEN PERMISSION FROM THE AUTHOR IS NOT ALLOWED.

       So remember:

       If you are example planning a game (like hm... X-TETRIS) or something
       commercial product, write to us and ask information about commercial
       license.


1.2 What is X-Mode Library for TP and TASM


       THIS IS "THE FINAL" RELEASE. THERE WERE TWO OLDER RELEASES (VERSIONS
       1.0 AND 1.1), BUT YOU MAY CALL THEM AS A BETA VERSIONS. NO WE ARE QUITE
       SATISFIED WITH THIS LIBRARY AND SO THERE ARE NOT ANYMORE ANY LARGE
       MODIFICATIONS COMING. OFCOURSE BUG FIXES, IF THERE ARE SOME BUGS AND
       SOMETHING LITTLE, BUT NOTHING SPECIALLY NEW.

       XMode Library for TP (XLIBTP) is a programming package for Borland's
       Turbo Pascal which provides capabilities to use vga's undocumented, so
       called x-modes. The reason why we made all this and published this is
       simple. We in Napalm Software needer a hi-res graphics with 256 colors,
       but we didn't want to use svga. So we found that x-modes would be our
       choice. We published this because we haven't found yet a good x-mode
       library for Turbo Pascal, so...

       BUT: What is x-mode?

       Vga cards have many special functions and registers. X-mode is one of
       those special things. X-mode means several different video modes, but
       this library doesn't use any other than 320 x ? and 360 x ?. If you
       want to use some other x-modes, you must try to find some information
       from bulletin board systems or books. Or you can try to modify our
       code...

       Originally term x-mode was used in a magazine called "Dr. Dobb's
       Journal", and it meant undocumented video mode of vga card (320x240).
       Some may hear tweaked mode, y-mode etc. These mean actually the same
       thing: Undocumented, higher performance vga mode than BIOS provides.
       Anyway we would say tweaked mode means 320x200x256x4 x-mode and term
       "x-mode" means any 256 color mode of vga which is not BIOS supported.
       That's our opinion.

       This library is produced with Borland's Turbo Pascal and so you need
       (if you want use it ;-)...) Turbo Pascal 6.0 or above. Because this
       library uses 286 code, you must have compiler directive $G+ on your
       programs installed. We think this library may be compiled with TP 6.0
       (we haven't tried), so don't kill yourself if you have TP 6.0 and this
       library don't work correctly.

       Bacause this library is distributed as a freeware, you can freely use
       and distribute it, if the rules in the license agreement are kept. BUT:
       Please include Napalm Software to your programs credits parts (If your
       product uses our library...) It's not hard to be nice for other 
       programmers?!

       The first version of this library included only one tiny asm source of
       x-mode. Now we have made a quite useful tweaked mode (One of x-modes,
       used in games very often.) library in asm. See subdirectory ASM for
       sources. And as allways... You use it, you notice us in credits!

       Current supported x-modes:

       -360x480, 1 display page
       -360x400, 1 display page
       -360x240, 3 display pages
       -360x200, 3 display pages
       -320x200, 4 display pages
       -320x400, 2 display pages
       -320x240, 3 display pages
       -320x480, 1 display page

       Major features:

       -Mouse routines
       -Enchanced drawing commands
       -Full x-mode source in pascal
       -Tweaked mode assembler sources
       -Fast code, assembler used

       Remarks: Because Antti made the code and I (Tapio) made the documents,
                in code I means Antti and in documents it means Tapio.

       
1.3 Hardware and software requirements


       Current system requirements:

       -A 286 or higher processor
       -A color vga adapter (Register compatible) and a color vga monitor

       Software requirements:

       -Turbo Pascal 7.0 (6.0 may also work, but we don't guarantee that!)
       -Turbo Assembler or compatible, if you want to use assembler parts of  
        this library

       No other requirements!


1.4 Example programs and important notices


       -XDEMO.PAS, main example:

       This example is the basic example of "How to use the x-mode routines?".
       It does rectangles, bar, polygons, circles (Ellipses!)... All the basic
       things. It should be easy to understand and follow.

       -XICON.PAS

       In case you haven't yet found out how to use our icon routines, and
       example  icons in your own projects. Try to follow this piece of code.

       -XTEST.ASM

       Assembler programmers x-mode pack. Only PutPixel and SetXMode routines
       are included. Asm programmers should be able to get/do others from our
       sources/somebody elses sources.

       -Don't forget to check the actual x-mode routines from xgraph.pas
       -Remember to check the tweaked mode routines from ASM subdirectory

       John Bridges has done a programming pack for Turbo C & Pascal which
       contains many BGI drivers including x-mode bgi drivers. They aren't
       fully compatible (At least weren't in our version of his library.), so
       our x-mode library may be a great help for programmers with such an
       "incompatible" vga. Antti's Vlb svga with OAK-077 chip didn't like them
       or actually Antti's monitor didn't like: It simply said
       "Screiaqioiiiii..." and went black, when Antti tried to use the
       TWEAK256-bgi driver. Tapio's svga with OAK-067 chip liked them. Hum,
       it's weird. But we think it much smarter to use his SVGABGI if you have
       a compatible vga.

       Ofcourse Borland guys haven't released source for the GRAPH.TPU, so if
       you want to learn something (we aren't prof.!) about programming...
       Yeah, and bgi fonts don't include 8 x 16 vga rom font used in this lib.

       We sincerely considered including John's TWEAK256.BGI to our lib for
       compatible vga owners, but we aren't so sure about the copyrights and
       we didn't want any harm to ourselves. ;-<.

       IDF2ICF.EXE converts Turbo Pascal Icon Designer format icons to format
       used in this library. Turbo Pascal Icon Designer (Version 1.0) is
       copyrighted by Andrew Ford 1991. We say thanks to Andrew, because his
       icon editor is very easy, good, nice... to use. Thank you! ;-).
       
       All of our routines aren't very fast, though we have optimized them.
       But it shouldn't bother you. If the speed is a problem (we think it's
       not a problem), try to do it by your own! We have anyway written most
       of the code with inline asm for speedup.

       Our MOUSE.TPU can be used in any vga's standard video mode (Assuming
       somekind of MS compatible mouse driver is installed). Just throw a call
       to SHOWMOUSE and GRAPHCURSOR! (In textmodes use SOFTWARECURSOR or
       HARDWARECURSOR instead). So we have now given you a toolkit to create a
       good mouse support to your programs, and a possibility to create your
       own x-mode programs with mouse support!

       PAL_FADEOUT proc doesn't need a graphics mode. If you have a VGA, you
       can use it in text-mode also. TRY! (None of the palette handling
       procedures needs a graph mode). :-).

       PUTSCALEDIMAGE proc is not yet complete. IT IS still TOO SLOW for us.
       But we haven't yet made it faster... Only one one thing to remember.
       When the scaling factors are less than 1 (The resulting bitmap is
       smaller than original), it uses faster technics with less
       calculations...

       SHADE_PALETTE proc has bugs. Want bug-free version? Just do it!

       Notes of future & asks for information:

       If you need 8086 compatibility in your programs, check our code and do
       this kind of changes: SHR AX,4; replace this with four SHR AX,1. It can
       be quite a job to do, but we don't need 8086 compatibility. :-(.

       EMS & XMS support is one of the features we are going to add to the
       library. We just need a little more information about XMS (We have some
       documents, but not enough.). If YOU know more things about XMS, please
       help us and send a letter to us!

       Currently library supports only eight x-modes, but in future there will
       be even more resolutions.

       Most of you own a 386, don't you? So we are going to write 386 code to
       library, without loosing 286 compatibility! Antti knows how to do it,
       but he haven't had yet time to do it.

       The speed question:

       Some people can't stand slow routines. We can't. Filled_circle -routine
       uses the fastest way of filling an area.


1.5 Release history of XLIBTP


       Version 1.0:

       We sincerely hope you didn't see this one. So bad and awful code. So
       slow... Only one resolution...

       Version 1.1:

       This version is much better and faster... All existing routines were
       enchanced to be faster and smaller. Mainly faster. Some bugs were
       corrected. Following routines were added to library:

       -Copy_Page
       -Show_page

       Tweaked mode asm routines were added to library.

       Version 1.2:

       Now, at last, the circles looks like circles and you can draw ellipses
       too! Palette cycling is also possible and high-level mouse routines are
       now in xgraph.tpu. Also we've done our own line routine. Original line
       routine was a stupid do-not-think-anything rip-off from ANIVGA 1.1. Our
       routine may be slower, but it should be much, much more easier to
       understand for a rookie. Old programming examples (xmode1.pas etc.) are
       now replaced by xdemo.pas. It demonstrates all meanfull things of this
       library. Also few small improvements there, and here.

       New routines:

       -Vline
       -Hline
       -FillPoly
       -Ellipse
       -FillEllipse
       -Textline
       -Palette_Cycle
       -Initialize_Mouse
       -Update_Mouse


1.6 What is Napalm Software


       In autum 1993, I and Antti got the idea: Let's start making of
       shareware programs, demos, programming utilities, anything! So founded
       Napalm Software. Now, a year later, we have released three products:

       -Advanced Module Player (AMP, the newest version is 2.11, AMP211.ARJ)
       -Napalm Software Info Package, which tells all meanfull things about    
        our team (NAPINFO1.ARJ)
       -This x-mode library
       -More are coming!

       If you want to know more things about Napalm Software, download our
       info package from some bbs or contact to us (Contacting info below).


1.7 How you can contact to the authors


       If you find a bug from this library, you have some problems, you want
       to join us, or you just have something to say, you can use following
       methods to contact us:

       By mail:

       C/O Napalm Software
       Tapio ijl
       Retkeilijntie 18 D 19
       SF-70200 Kuopio
       Finland, Europe

       By e-mail:

       tapio.aijala@mpoli.fi

       By calling our home bbs, Astral Plane:

       +358-(9)73-733148

       V.32bis, 24h, SPO and Nordic Visions WHQ, Demos and sources and more...

       Remarks: You can find allways the newest versions of Napalm Software's
                products from Astral Plane! Call now!


2.0 Installing XLIBTP

2.1 Distribution package


       XLIBTP is distributed in one, packed archive file created by ARJ.
       Before you can use XLIBTP you have to unpack it with ARJ.

       Example: How to unpack distribution package if ARJ.EXE is in the path
                and you want to unpack XLIBTP to C:\XLIBTP and if packed
                XLIBTP is in drive A:

                ARJ X A:\XLIBTP12.ARJ C:\XLIBTP

       Files that should be included in this archive:



 DEFAULT.ICF    -- Icon file used by XICON.PAS. Converted from IDF
 FILE_ID.DIZ    -- Id for this package
 IDF2ICF.EXE    -- Icon convertor
 LICENSE.TXT    -- Napalm Software shareware license agreement
 MOUSE.INT      -- Interface of mouse.tpu
 MOUSE.TPU      -- Napalm Mouse Unit for Turbo Pascal 7.0 and above
 ORDER.TXT      -- Order form for Napalm Software shareware products
 SUPPORT.TXT    -- List of Napalm Software support bbs's
 SYSOP.TXT      -- How to become Napalm Software support site
 TPU2INT.EXE    -- Cuts interface part from unit source code. Dumm.
 XDEMO.EXE      -- XLIBTP demonstration
 XGADR.LIB      -- Pascal version of putpixel row offsets
 XGADR.PAS      -- Tiny, simple example for beginners |-<
 XGRAPH.PAS     -- The "kernel" of lib. Actual xmode routines are here.
 XGRAPH.TPU     -- The XMODE library unit for Turbo Pascal 7.0 and >
 XICON.PAS      -- Shows you how to use our icon handlings. Useful? NOT!->
 XMODE.TXT      -- This text file, documents of this lib
 XDEMO.PAS      -- First run this program to see what's XLIBTP made of!

 ASM            -- Directory containing asm sources:
  8X8FONT.INC   -- 8x8 rom font
  EATME.NOW     -- Readme file...
  SCROLLER.ASM  -- This source has nothing to do with XMODE, but it's here    
                   anyway!
  TWEAKED.ASM   -- Tweaked mode library for TASM/MASM version 1.00. Read
                   documents for library from this file.
  TWEAKTST.ASM  -- Example of using tweaked library
  XGADR.INC     -- ASM version of PUTPIXEL row offsets
  XTEST.ASM     -- Example of using and switching to xmode with ASM



       Please DON'T remove any files from distribution package. Somebody might
       need them! Thanks.


2.2 Installing XLIBTP


       Installing of XLIBTP is very easy. You just have unpack it and that's
       it! No difficult setups, just start coding! Look unpacking example from
       previous chapter.


2.3 Ready to use XLIBTP


       Now XLIBTP is installed and ready for use. BUT: Please read carefully
       this manual before starting using XLIBTP! You learn how to use even
       every little thing of XLIBTP and you can find some hints and tips to
       help you at your's programming project. Happy coding!


3.0 Reference guide

3.1 How to use reference guide


       In this reference guide, are all of these procedures and
       functions listed in alphabetical order. There you can find all
       of that information which tells to you "How to use these
       routines?". There you find also information about variables and 
       consts used in this library.


Bar procedure


       Function: Draws a bar to screen (Same as in TP's graph unit.).

       Syntax: Procedure Bar(x, y, x2, y2 : Word; color, page : Byte)

       Options:

       x       Position of the upper-left corner (x coordinate)
       y       Position of the upper-left corner (y coordinate)
       x1      Position of the lower-right corner (x coordinate)
       y1      Position of the lower-right corner (y coordinate)
       color   Color of the bar
       page    Display page


BigOutText procedure


       Function: Outputs text using vga's 8x16 rom font.

       Syntax: Procedure BigOutText(x, y : Word; color, page : Byte;
                                    text : String)

       Remarks: Fonts are stored in an array created by
                SetXMode procedure and you can modify that
                array directly!

       Options:

       x       X coordinate where text is outputted
       y       Y coordinate where text is outputted
       color   Color of text
       page    Display page
       text    Text to output


Circle procedure


       Function: Draws a circle using x and y as the center point with rad as 
                 radius and color as color.

       Syntax: Procedure Circle(x, y, rad : Word; color, page : Byte)

       Options:

       x       X coordinate to center point
       y       Y coordinate to center point
       rad     Radius
       color   Color of circle
       page    Display page


Copy_Page procedure


       Function: Copies picture from inpage to outpage.

       Syntax: Procedure Copy_Page(inpage, outpage : Byte);

       Remarks: Use only in modes that supports more than one display page!

       Options:

       inpage  Source page
       outpage Destination page


Ellipse


       Function: Draws an ellipse to screen.

       Syntax: Procedure Ellipse(mx, my, a, b : Word; c, p : Byte);

       Options:

       mx      X coordinate of center point
       my      Y coordinate of center point
       a       Horizontal radius
       b       Vertical radius
       c       Drawing color
       p       Display page


FilledCircle procedure


       Function: Draws a filled circle of specified color.

       Syntax: Procedure FilledCircle(x,y,rad : Word; color, page : Byte)

       Options:

       x       X coordinate of center point
       y       Y coordinate of center point
       rad     Radius
       color   Color of circle (Fill circle with this color too.)
       page    Display page


FillEllipse procedure


       Function: Draws a filled ellipse of specified color.

       Syntax: Procedure FillEllipse(mx, my, a, b : Word; c, p : Byte);

       Options:

       mx      X coordinate of center point
       my      Y coordinate of centre point
       a       Horizontal radius
       b       Vertical radius
       c       Drawing color
       p       Display page


FillPoly procedure


       Function: Fills a polygon.

       Syntax: Procedure FillPoly(size : Integer; Var polygon; c, pa : Byte);

       Options:

       size    Number of corners in polygon
       p       Array where are coordinates of corners
       c       Filling color
       pa      Display page


FillScreen procedure


       Function: Fill whole screen with specified color.

       Syntax: Procedure FillScreen(color, page : Byte);

       Options:

       color   New color of screen
       page    Display page


FreeImageMem procedure


       Function: Frees memory reserved by GetImage.

       Syntax: Procedure FreeImageMem(image : Pointer)

       Remarks: Result will be a nice crash, if pointer is not a valid image   
                pointer, but is not nil!

       Options:

       image   Pointer to picture captured by GetImage


GetImage function


       Function: Captures piece of screen. Returns 0 if no erros and 1 if no    
                 memory available.

       Syntax: Function GetImage(x, y, x1, y1 : Word; Var image : Pointer;    
                                 page : Byte) : Word;

       Options:

       x       Position of the upper-left corner (x coordinate)
       y       Position of the upper-left corner (y coordinate)
       x1      Position of the lower-right corner (x coordinate)
       y1      Position of the lower-right corner (y coordinate)
       image   Pointer to picture
       page    Display page


GetPalette procedure


       Function: Gets the actual vga palette to variable PAL.

       Syntax: Procedure GetPalette

       Options:

       None.


GetPixel procedure


       Function: Gets color of pixel specified in x and y. Color will be in 
                 var COL.

       Syntax: Procedure GetPixel(x, y : Word; page : Byte);

       Remarks: Starting offset of visible screen is taken care, so X,Y
                coordinate 10,10 means 10,10 on screen, not in video memory!
                See putpixel routine's explanation for more details about
                this.

       Options:

       x       X coordinate
       y       Y coordinate
       page    Display page


Hide_Cursor procedure


       Function: Hides cursor from text modes.

       Syntax: Procedure Hide_Cursor;

       Remarks: Works only in text modes!

       Options:

       None.


HLine procedure
-

       Function: Draws a horizontal line.

       Syntax: Procedure HLine(x1, x2, y : Word; page, color : Byte);

       Options:

       x1      First x coordinate
       x2      Second x coordinate
       y       Y coordinate
       page    Display page
       color   Drawing color


Initialize_Mouse function


       Function: Inits a mouse. Returns 0 if everything went ok, 1 if no 
                 mouse detected.

       Syntax: Function Initialize_Mouse : Boolean;

       Options:

       None.


LoadIcon procedure


       Function: Loads a specified Napalm format 256 color icon. Returns 0 if  
                 erros, 1 if file wasn't found, or it was corrupted. Returns  
                 2 if not enough memory was available for image. Erros are    
                 returned in variable XMODEERR.

       Syntax: Procedure LoadIcon(filename : String; var icon : Pointer; ino :
                                  Integer);

       Options:

       filename  Name of the icon file to be loaded
       icon      Pointer to memory where icon be loaded
       ino       Indicates which of 32 icons is loaded from the icon file   

 
OutText procedure


       Function: Same as BigOutText, but uses vga's 8x8 rom font.

       Syntax: Procedure OutText(x, y : Word; color, page : Byte; text :       
                                 String);

       Options:

       x       X coordinate where text is displayed
       y       Y coordinate where text is displayed
       color   Color of text
       page    Display page
       text    Text to output


Palette_Cycle procedure


       Function: Cycles palette.

       Syntax: Procedure Palette_Cycle(start, stop, direction : Byte);

       Options:

       start     First color in cycle
       stop      Last color in cycle
       direction Cycle foreward or backward


Pal_FadeOut procedure


       Function: Fades out vga's palette, uses speed as parameter to delay     
                 command.

       Syntax: Procedure Pal_FadeOut(speed : Byte);

       Options:

       speed   Speed to crt unit delay command


PutImage procedure


       Function: Puts picture stored with GetImage to screen.

       Syntax: Procedure PutImage(x, y : Word; Var image : Pointer; page :     
                                  Byte)

       Options:

       x       X coordinate where to put picture
       y       Y coordinate where to put picture
       image   Pointer of picture stored with GetImage
       page    Display page


PutPixel procedure


       Function: Draws a single pixel to screen.

       Syntax: Procedure PutPixel(x, y : Word; color, page : Byte);

       Remarks: Putpixel uses the pixel coordinates so, that the starting
                offset of visible screen is taken care, but only if you set it
                with XGRAPH.TPU SETOFFSET routine. If you set a pixel in XY
                10,10. Then you change offset with SETOFFSET procedure. Now
                you set a pixel in XY 10,10. It's on the same place on screen,
                but in different place in video memory. Now if you scroll the
                screen you'll see it.

       Options:

       x       X coordinate to put pixel
       y       Y coordinate to put pixel
       color   Drawing color
       page    Display page


PutScaledImage procedure


       Function: Scale picture using scalex and scaley and then draw it to     
                 screen. Smaller number means smaller picture.

       Syntax: Procedure PutScaledImage(x, y : Word; scalex, scaley : Real;
               Var image : Pointer)

       Options:

       x       X coordinate to put picture
       y       Y coordinate to put picture
       scalex  Scale ratio x
       scaley  Scale ratio y
       image   Pointer of picture stored with GetImage


Rectangle procedure


       Function: Draws a rectangle to screen.

       Syntax: Procedure Rectangle (x, y, x1, y1 : Word; color, page : Byte)

       Options:

       x       Position of the upper-left corner (x coordinate)
       y       Position of the upper-left corner (y coordinate)
       x1      Position of the lower-right corner (x coordinate)
       y1      Position of the lower-right corner (y coordinate)
       color   Color of the rectangle
       page    Display page


SaveIcon procedure


       Function: Saves a specified icon to a specified icon of a specified     
                 icon file. Huh? Returns error code in variable XMODEERR.

       Syntax: Procedure SaveIcon(filename : String; Var icon : Pointer; ino :
                                  Integer)

       Remarks: Icon must be a image returned by LoadIcon procedure, or
                GetImage procedure. If image is returned by GetImage, it must
                be 32x32 sized. Otherwise some errors and problems will be
                caused.

       Options:

       filename  Name of the file where icon should be saved
       icon      Pointer to icon
       ino       Number of place where icon should be saved in icon file
                 (1-32)


SetBorder procedure


       Function: Sets new border color.

       Syntax: Procedure SetBorder(color : Byte);

       Options:

       color   New border color


SetLineComp procedure


       Function: Sets up line compare split. Only bits 0-9 of newcomp are 
                 used.

       Syntax: Procedure SetLineComp(newcomp : Word);

       Options:

       newcomp New line compare split


SetOffset procedure


       Function: Sets new starting offset of visible screen.

       Syntax: Procedure SetOffset(offs : Word);

       Remarks: Smooth scrolls can be performed with this procedure. Works
                correct in any 256 color VGA mode. New offset is taken care in
                putpixel and getpixel procedures, and because of that in every
                other graphics procedure/function.

       Options:

       offs    New starting offset


SetPalette procedure


       Function: Sets all vga palette registers from variable PAL.

       Syntax: Procedure SetPalette;
       Options:

       None.


SetRGB procedure


       Function: Same as SetRGBPalette in graph unit, but faster.

       Syntax: Procedure SetRGB(color, rvalue, gvalue, bvalue : Byte);

       Remarks: Vars are bytes, but only RGB values 0-63 take effect. See also
                SetPalette routine.

       Options:

       color   What color will be changed (0-255)
       rvalue  Value of red
       gvalue  Value of green
       bvalue  Value of blue


SetViewPort procedure


       Function: Sets view port's size.

       Syntax: Procedure SetViewPort(x1, y1, x2, y2 : Word);

       Options:

       x1      X coordinate of upper-left corner
       y1      Y coordinate of upper-left corner
       x2      X coordinate of lower-right corner
       y2      Y coordinate of lower-right corner


SetXMode function


       Function: Sets vga to undocumented mode called "X-Mode".

       Syntax: Function SetXMode(modus : Byte) : Byte;

       Remarks: Returns 0 if no erros or 1 if no vga. Supported x-modes are:

       0 = 360 x 480, 1 display page
       1 = 360 x 400, 1 display page
       2 = 360 x 240, 3 display pages
       3 = 360 x 200, 3 display pages
       4 = 320 x 200, 4 display pages
       5 = 320 x 400, 2 display pages
       6 = 320 x 240, 3 display pages
       7 = 320 x 480, 1 display page

  Options:

  modus   Which x-mode to set


Shade_Palette procedure


       Function: Makes a palette shading within the s start-stop range, with    
                 rgn values sr, sg, sb, er, eg, eb.

       Syntax: Procedure Shade_Palette(start,stop,sr,sg,sb,er,eg,eb : Byte);

       Options:

       Listed above.


Show_Page procedure


       Function: Shows display page given in variable PAGE.

       Syntax: Procedure Show_Page(page : Byte);

       Remarks: Use only in modes that support more than one display pages.

       Options:

       page    Page's number


SyncRetrace procedure


       Function: Syncs with retrace signal. Smooth animations, and timing.

       Syntax: Procedure SyncRetrace;

       Options:

       None.


TextLine procedure


       Function: Draws line using given text.

       Syntax: Procedure TextLine(x1, y1, x2, y2 : Word; color, page, font :   
                                  Byte; text : String);

       Options:

       x1      X coordinate of line's starting point
       y1      Y coordinate of line's starting point
       x2      X coordinate of line's ending point
       y2      Y coordinate of line's ending point
       color   Drawing color
       page    Display page
       font    Which rom use
       text    Text to output


TextMode procedure


       Function: Sets vga to text mode 3 (common 80x25 and 16 color mode).

       Syntax: Procedure TextMode;

       Options:

       None.


Update_Mouse procedure


       Function: Updates mouse cursor's place on screen.

       Syntax: Procedure Update_Mouse;

       Options:

       None.


VLine procedure


       Function: Draws a vertical line.

       Syntax: Procedure VLine(y1, y2, x : Word; page, color : Byte);

       Options:

       y1      First y coordinate
       y2      Second y coordinate
       x       X coordinate
       page    Display page
       color   Drawing color


3.2 Variables, consts and types


       In this list are listed most of these variables used in our library
       which values you can directly modify in your program if you want to.

       Consts:

                MaxColor = 256             Maximium number of colors

                NoError = 0                Error codes returned in variable
                                           XMODEERR
                FileInvalid = 1
                FileNotFound = 1
                NotEnoughMemError=2

                NormalPut=0                Style codes passed to PutImage and
                                           PutScaledImage routines in variable
                                           PUTIMGSTYLE
                XORPut=1
                BackGroundPut=2



       Types:

                Type PaletteType = Record 
                  Red : Array [0..255] of Byte;
                  Green : Array [0..255] of Byte;
                  Blue : Array [0..255] of Byte;
                End;

       Variables:

       Col : Byte                          Color variable
       Pal : PaletteType                   Palette variable
       Font : Array [0..255*8] of Byte     Array where 8x8 rom font is
       BigFont : Array [0..255*16] of Byte Array where 8x16 rom font is
       XmodeErr : Integer                  Variable to indicate XMODE errors
       PutImgStyle : Integer               The style to PutImage and
                                           PutScaledImage routines
       XMax, YMax : Integer                Maximium x and y coordinates


3.3 Data formats


       XGRAPH.PAS Image Data Format (Used by GetImage, PutImage etc.)
       
 
       Header data format: 
                          
       Offset   Length  Meaning 
       
       0        word    The size of image data (Header not included) 
       2        word    X-size of image                              
       4        word    Y-size of image
       6-       1-      Pixel data, header ends                     
       
 
       Pixel data format: 
 
       Each byte indicates the according pixel color. For example, 20 pixels
       tall, and 5 pixels wide image is stored as follows: 
 
       Ŀ 
       12345 Pixels 1-5, starting from upper left corner to right 
       67890 Pixels 6-10, starting from second row, left to right 
       ..... 

              
       Icon File format
       
 
       Icon file format is really stupid, and so it's easy to understand.
       Icons are not packed in any form, but a 6 bytes long header is included
       to file to make sure that it's a valid icon file before loading an
       icon. Don't worry a much about our format. Don't try to understand why
       it's so. Just relax, and use it!
                         
       Offset  Length   Meaning 
       
       0       6 bytes  Text "ICON94". For checking is the file icon file.
       6       ?        32 icons data 


4.0 Tips and tricks


4.1 Palette routines


       Palette routines included to XLIBTP can be used not only in x-modes, 
       but in other video modes too! You can example write something to screen 
       in text mode and then just fade palette away! Cool or what do you 
       think? :)


4.2 Split screen


       Do you want to divide screen to two sperate parts? If you do, split
       screen routine is just for you! Using it you can create example a
       plasma efect so that there is a scrolling plasma in upper part of 
       screen and in lower part of screen is a scrolling texto. Read
       XDEMO.PAS to see how you can do it (If you don't know yet!).


5.0 Utilities included to XLIBTP


       Remarks: Well, what's the point with this? Nothing, we just needed this
                kind of applications for our products, and so we created them.
                If you don't need these, removing them are as easy as DEL
                command. ;-). But please DO NOT remove them from that package
                you are distributing, somebody might need them. Thanks.
 
                All of our utils included to XLIBTP are distributed as they
                are. No any warranties are given. You use these products at
                your's own risk and resbonsibility.


5.1 IDF2ICF.EXE


       IDF2ICF.EXE is a little icon converter. It converts Turbo Pascal Icon
       Desinger format icons to format used in XLIBTP. Turbo Pascal Icon
       Designer's icon format uses only 16 colors, so the resulting icon file
       will be larger, because of using all 256 colors.
 
       Usage:

       IDF2ICF [source file] [destination file]


5.2 TPU2INT.EXE


       TPU2INT.EXE is a stupid source code converter. It takes the "public"
       interface part from Turbo Pascal unit source code, and writes it to a
       new file. Convertor is stupid, because only error checking it makes is:
       "Did I get enough parameters for source and destination files?".


5.3 MOUSE.TPU (For TP 7.0 and above)

 
       Read mouse.int text file if you want to use mouse.tpu in your own
       programs. Remember that it's copyrighted by Napalm Software too. It's
       freeware and so you can distribute it freely, but using in commercial
       products is not allowed. Remember also that it's distributed as it is
       and no warranties are given. You use it in your own risk! As in all our
       products... Use it and notice us in credits. 


6.0 Assembler part of XLIBTP

6.1 What is tweaked-mode


       Tweaked mode is one of the x-modes (320 x 200, 4 display pages). Many
       games and demos use it, because animations and scrolling are very easy
       to do with it (Thanks to 4 display pages!).


6.2 How to use assembler sources


       If you want to use assembler sources of this library, you have to be
       experienced with assembler language and so we think that you can learn
       easily to know how to use them without any reference manual about that
       topic (If you know how to do assembler code, we think that you know how
       to read comments from sources, don't you?). So, just read comments from
       assembler sources and study by that way (Are we just lazy, because there
       is no manual for asm sources written? Not... :).


7.0 Special info about programming vga 

7.1 Virtual screen

 
       Remarks: The following number values are written for x-mode 360x480.

       Now, we have given you tools to create x-mode programs, but you might
       want to create your own routines, and play tricks with x-mode. One
       reasonable trick is virtual screen. This idea is shown in figure 1.0
       below:



       Figure 1.0
 
       Ŀ    Ŀ
       XXXXXXXXXXXXXXXXXX     
       XXXXXXXXXXXXXXXXXX      The visible screen
       XXXXXXXXXXXXXXXXXX     
       XXXXXXXXXXXXXXXXXX    
       Ĵ
        Non-visible part 
        of vga 256 Kb    
        video mem. This  
        part and visible 
        screen together  
        are the virtual  
        screen.          
        



       Now let's say that the place of visible screen part in video mem can be
       easily changed. Think what happens... The screen scrolls! This IS a
       reasonable trick with x-mode, isn't it?
  
       Then how to change the place of visible screen? This isn't hard. You
       see, vga has actually only one register for that, but it is split to
       two parts: HB starting offset and LB starting offset of visible screen.
       (Here is one good side of 256 color modes: No need for preset row scan,
       or horizontal panning.) To write/read these registers, you'll need to
       do some I/O with vga. First select index from port 3d4h. Use 0Ch to HB
       starting address, and 0Dh for LB starting address. Then you can do your
       I/O with port 3d5h.
 


       Example 1.0

       Port[$3D4] := $0C;
       Port[$3D5] := Hi(New_Offset);
       Port[$3D4] := $0D;
       Port[$3D5] := Lo(New_Offset);



       One could easily think: "It is easy, let's just increment our counter
       with 360 to scroll one pixel row at time." Well, it isn't. The correct
       increment is 360 / 4 = 90. Why this, you ask. Because the whole 256Kb
       can't fit to system ram under 1Mb, vga uses special techniques with
       it's memory. These are explained later. 

       Above example works fine, but has few problems. The screen is not
       stabile and scroll is too fast. Both can be corrected by watching
       retrace just before changing offset. 
 


       Example 1.1

       ASM
        CLI
       End;
       While Port[$3DA] And 8 = 0 Do;
       Port[$3D4] := $0C;
       ...
       ...
       ...
       ASM
        STI
       End;



       Readings from port 3DAh means sync with VRI signal, which occurs in
       same rate in all machines. Assembler command CLI means that mask of
       maskable interrupts, so that interrupt can't occur while I/O. STI
       command means that enable maskable interrupts.
 
       Show_Page procedure in our library uses SetOffset to show a specified
       display page. Now you understand it too!
 
       There's one more problem. Our library uses only the start of video mem,
       the first 90*480 bytes. So if you want something more than just a
       scroll with hi-res random graphics you need to do a PutPixel, that uses
       the whole 256Kb of vga video mem. Some of you could easily change our
       ASM source a bit and that's it. But we assume you would like to
       understand vga a little better. THIS EXPLANATION OF OUR XMODE IS ALSO
       THE EXPLANATION OF VGA'S SO CALLED TWEAKED MODE. ONLY RESOLUTION
       DIFFERS. So if you have a tweaked mode sprite library/unit (like
       ANIVGA, or SPX) you can now understand it better, and even write your
       own sprite TPU!


7.2 How vga uses it's 256 Kb video mem in the tweaked or/and xmode

 
       Remarks: VIDEO MEM IS PLACED AT SEGMENT A000h. ONLY THIS SEGMENT IS
                USED!

       How to fit 256Kb to 64Kb???!!



       Figure 2.0

       Ŀ
       1234123412341234123412341234 Video memory image
       ...                         
       ...                         



       The physical memory is located in vga controller. But in segment A000h
       the memory is mapped depending on MAP MASK, and READ MAP SELECT
       registers. As you see, we have written some numbers to video mem. They
       indicate pixels. Map mask register bit 1 is pixels numbered 1 write
       enable if set, Map mask register bit 2 is pixels numbered 2 write
       enable if set... Set all Map mask bits on, and you can acces 4 pixels
       with one byte! Read map select is same as map mask, but means read
       enable for each plane. Note: This is valid info only if vga write mode
       0 is set. It usually is. 

       Now refer to XTEST.ASM and specially to it's PutPixel routine and you
       should be able to make a xmode scroller program, that can use all of
       vga's 256 Kb video memory.
 
       Remarks: XTEST.ASM doesn't show the read map select register. Read map
                select is handled by the following method: First select index
                from port 3CEh, by placing number 4 to it. Then use 3CFh as
                read map select.
 


       Example 2.0

       Port[$3CE] := $4;
       Port[$3CF] := ReadMask;



       On some vga cards it's not that easy. In our vgas this does fine, our
       friend's vgas too. BUT: We have heard that with some vga cards read map
       select uses only bits 0-1. So number 0 means plane 1 can be read. 1
       means plane 2 can be read, 2 that plane 3 can be read... Anyway try
       first with our method. Number 1 means plane 1, 2 means 2, 4 means 3, 8
       means 4. 15 means all together.


7.3 Write mode 1

 
       Vga has four so called write modes. In normal cases write mode 0 is
       used. But because write mode 1 is much much faster, it should be used
       when possible. There are certain restrictions on using it anyway. In
       write mode 1 it's easy and fast operation to copy an area of video
       memory to elsewhere in video memory (SCROLLING!!!...) (See Copy_Page).
       It's okay to use REP MOVSB with this, without plane selections! But
       using REP MOVSW, or REP MOSVD (386 instruction) doesn't work. This is
       because of vga's internal latch width is 8 bits. Another restriction is
       that because write mode 1 copies bytes and one byte contains 4 pixels
       (remember?)... We can only operate with 4 pixel movements! While
       copying the whole page this doesn't matter. If you want information
       about the other write modes, write to us or try to find some books
       (Programmer's Guide to the EGA and VGA Video Cards, Richard Ferraro,
       Addison-Wesley).


7.4 640 x 400 xmode

 
       Vga has 262144 (exact) bytes of memory. 640x400 resolution with 256
       colors needs 240000 bytes. We haven't yet found a reason, why it
       couldn't be used! (We haven't found a way to use it, though). Currently
       we are working to find a way to use it. Monitors won't be a problem,
       VGA has 640x480 16 color mode. Xmodes are interesting because of this:
       The resolution can be actually quite freely selected. "Standard" xmode
       resolutions just are those ?x240, ?x480, 360x?, 320x?, ?x200 and ?x400.
       We figured this out, when we made a 400x480 xmode with asm.

 
7.5 Vertical resolution


       Vga controller port address 3D4h, index 9 controls the cell height.
       ?x240 xmode is created by making 480 scan lines, but cell height 2. It
       can be used to double, triple ... the pixel vertical size! So 160, 120
       and 100 as y resolutions are easy to create now. Ofcourse graphic will
       look awful with just 100 pixels in y axis.


7.6 Horizontal resolution

 
       There's an easy way to make horizontal resolution smaller. Simply
       select all planes from map mask select. Now there's 80 pixels on 320
       screen! (Again... The graphic looks awful, and you have to do new
       PutPixel etc. procedures). These very small resolutions are useful when
       you've done an effect, which needs a lot of processor power (Flames!
       Plasma!).


7.7 X-mode games

 
       Yeah, why not. But notice, that in 320x200 resolution (normal game
       resolution), you have 4 display pages, and less pixels. This makes
       updating screen faster, and programming easier.  We think that it would
       be nice for those 486DX/66 Mzh users to have bigger resolutions. For
       example MS Flight Simulator uses 320x400 xmode. Remember also that our
       library isn't designed to be used in action games. So you have to do
       your own sprite routines if you want to use x-mode.

7.8 Filling style


       This chapter is meant to show you the idea of almost all filling
       routines. The method, which can be used to fill almost anykind of
       polygon.

       Let's say we need to fill the polygon below: 



       Figure 3.0
 
        \\ 
         \            \  
          \\ 

 
       
       Now first thing to do is to calculate the coordinates for pixels on
       each side (Supposing you know how to draw a line, this shouldn't be a
       problem). Now when the coordinates are in array, you need to do some
       sorting. 
         
       Sort 1: 
 
       1. From up to down, take all the pixels in current y coordinate of     
          sort, and find the smallest, and the biggest. These are placed in   
          another array. 
 
       2. Take next y coordinate, and go through the polygon like this... 
 


       Figure 3.1
 
        \These points\    <---This is the biggest x in the top y coordinate 
         \are all.....\ 
          \meanless....\ 
           \by now!.....\ 
         


        Now just draw the horizontal lines in each y coordinate, taking 
        x values from our array!


8.0 It's time to end

8.1 Last words


       It's the ending time. Antti and I have spended many, many hours and
       sleepless nights to this product and we hope that you found it usefully
       and easily to use. If you liked it and you want to make us happy: Send
       a postcard or letter to us! Or just write some e-mail. It's nice to get
       mail from peoples around the world which are using your's own product.
       And if you make some product that uses this library, could you please
       be so kind and send your's product to us. We would like to know what
       kind of products uses our library.

       Code may still be QD (= Quick & Dirty), but we have tried to make it
       better. Especially we would like to know how we could do our routines
       better (We are sure there are better than ours). :-).

       This library propably contains few bugs, so if you find any, could you
       please be so kind and report them to us. Because we can't correct bugs
       we don't know! 
 
       If you want help us economically, send your moneys, checks, credit
       cards, computers, disks or anything to us. Letter bombs will be
       returned to sender! 
 
       All suggestions, comments etc. welcome!
 

8.2 Greetings, credits and thanks to


       -John Bridges, VGAKIT
       -Kai Rohrbacker, ANIVGA
       -Finn Thoegersen, VGADOC
       -Andrew Ford, Turbo Pascal Icon Designer
       -Mikko Piironen, Comments about XGRAPH before releasing it
       -AARDVARK, Nice sources which they have released
       -Jozsef Ferincz, Nice BP7SB ver. 1.01 source beautifer
       -Users of this library
       -And to all others...

       THANKS!


8.3 Special to artists


       Currently we are looking for an artist, who is able to draw cute
       pictures in any video mode with 256 colors. If you are the person we
       are looking for, and want to join us, throw a letter. We can't
       guarantee any money, fame or anything, but if you still want to join
       us... YOU ARE THE ONE WE NEED!
