home *** CD-ROM | disk | FTP | other *** search
/ Power CD-ROM!! 7 / POWERCD7.ISO / prgmming / vgfx10 / vgfx.doc < prev    next >
Text File  |  1994-11-30  |  44KB  |  1,296 lines
  1.  
  2.                  VGFX v1.00  (C) Copyright 1994 Bill Quesnel
  3.                  -------------------------------------------
  4.                Design & Coding by Bill Quesnel & Brian Manning
  5.  
  6.  
  7. * What is VGFX?
  8. ---------------
  9.  
  10.     VGFX is a graphics engine that provides animation routines for the
  11.     320x200x256 VGA x-graphics mode.  This mode supports 4 video pages
  12.     which can be used to generate ultra-SMOOTH animations!  Other feat-
  13.     ures of the library include:  mouse  &  joystick support,  loading
  14.     of PCX and BMP pictures, palette routines, fonts and Sound Blaster
  15.     support for playing digitized voice (VOC) files.
  16.  
  17.  
  18.     Here's a summary of features:
  19.  
  20.     o Page-flipping engine for ultra-smooth animation, page
  21.       flipping is the best way to create smooth animations on
  22.       the PC, now you can do it too!
  23.  
  24.     o Mouse and Joystick/Gravis GamePad supported!
  25.  
  26.     o SoundBlaster .VOC support from 1-44khz sampling rates,
  27.       these routines are totally independant of VGFX, so you
  28.       can use these routines without having to use VGFX!
  29.        (Requires a SoundBlaster or compatible sound card)
  30.  
  31.     o GLIB, a utility that allows you to store all kinds of
  32.       files in one massive database 'library'.  All of VGFX's
  33.       routines support this 'library' format.  Wouldn't your
  34.       programs look better if they had one big data file vs.
  35.       2000 little data, picture and sound files?  These
  36.       routines only add around 7ms overhead vs. traditional
  37.       file handling!!
  38.  
  39.     o EMS memory support.  These routines allow you to store
  40.       anything (including sprites/images) in EMS memory so
  41.       you can fit more data!  (Requires LIM EMS 3.0 or later)
  42.  
  43.     o Image format support, VGFX supports PCX reading and BMP
  44.       reading/writing!
  45.  
  46.     o Palette manipulation & fading.
  47.  
  48.     o Fonts.. 31 fonts included, you can underline fonts, make
  49.       them double wide/high or make them italic!
  50.  
  51.  
  52.  
  53.  
  54. * How do I use VGFX?
  55. --------------------
  56.  
  57.     To install VGFX you need to copy the VGFX.TPU into the directory
  58.     where you keep your Units.  For example:
  59.  
  60.         COPY VGFX.TPU C:\BP\UNITS
  61.  
  62.     After you have completed this you are ready to use VGFX!  You need
  63.     only to inlcude VGFX in your uses statement:
  64.  
  65.     Program Sample;
  66.     Uses Crt, Dos, VGFX;
  67.  
  68.     Var
  69.     . . .
  70.  
  71.  
  72. * What do I get when I register?
  73. --------------------------------
  74.  
  75.     The latest version of VGFX which does not contain the 5 second
  76.     registration delay.  You will also recieve hints & tips on how
  77.     to develop games using VGFX.  This will automatically ensure
  78.     that you will get future updates of VGFX for the upgrade price
  79.     of $5.
  80.  
  81.  
  82.  
  83. * VGFX Routine Summary
  84. ======================
  85.  
  86.  
  87. * VGFX_Init
  88. -----------
  89. Name        : VGFX_Init
  90. Declaration : Function VGFX_Init : Boolean;
  91.  
  92.   Initializes the video card & routines, these routines use the 320x200
  93.   256-color VGA x-mode, the screen is represented in pixels starting at
  94.   0,0 to 319,199 (320x200).  There are four video pages this engine uses,
  95.   they are numbered 1-4.  This only needs to be called once at the
  96.   begining of your program.  This function returns FALSE if the user
  97.   does not have VGA otherwise TRUE.
  98.  
  99.  
  100. * VGFX_Done
  101. -----------
  102. Name        : VGFX_Done
  103. Declaration : Procedure VGFX_Done;
  104.  
  105.   Restores the video card to it's previous state (i.e.- text mode) and
  106.   uninitializes the video routines.  This routine is not required to
  107.   be called at the end of your program.  When your program terminates,
  108.   whether by normal termination (i.e.- end of the program) or by
  109.   runtime error, these routines will still restore the video card
  110.   and free allocated memory.
  111.  
  112.  
  113. * Clearscreen
  114. -------------
  115. Name        : ClearScreen
  116. Declaration : Procedure ClearScreen (color : byte);
  117.  
  118.   This procedure clears the screen on the specified page with the
  119.   given color.
  120.  
  121.   (See also: SetWorkPage)
  122.  
  123.  
  124. * GetPixel
  125. ----------
  126. Name        : GetPixel
  127. Declaration : Function GetPixel (x, y : integer) : Byte;
  128.  
  129.   This function returns the color at the current X/Y pixel position.
  130.  
  131.  
  132. * PutPixel
  133. ----------
  134. Name        : PutPixel
  135. Declaration : Procedure PutPixel (x, y : integer;  color : byte);
  136.  
  137.   The procedure draws a pixel at x/y using the specified color.
  138.  
  139.   (See also : SetWorkPage)
  140.  
  141.  
  142.  
  143. * GetImage
  144. ----------
  145. Name        : GetImage
  146. Declaration : Procedure GetImage (var pict   : array of byte;
  147.                                   x, y, w, h : integer);
  148.  
  149.   This procedure grabs an image from the specified video page (page 1
  150.   2 or 0).  It gets the image from the current x/y with the specified
  151.   w and h.  This procedure does not support clipping!  Make sure not
  152.   to go outside the 320x200 boundaries.
  153.  
  154.  
  155.   (See also : SetWorkPage)
  156.  
  157.  
  158. * PutImage
  159. ----------
  160. Name        : PutImage
  161. Declaration : Procedure PutImage (var pict   : array of byte;
  162.                                   x, y, w, h : integer);
  163.  
  164.   This procedure puts an image on the specified video page (page 1
  165.   2 or 0).  It puts the image at the current x/y with the specified
  166.   w and h.
  167.  
  168.   (See also : SetWorkPage)
  169.  
  170.  
  171. * FlipImage
  172. -----------
  173. Name        : FlipImage
  174. Declaration : Procedure FlipImage (var pict   : array of byte;
  175.                                    x, y, w, h : integer);
  176.  
  177.   This procedure puts an image on the specified video page (page 1
  178.   2 or 0).  It puts the image at the current x/y with the specified
  179.   w and h.  The image is drawn to the screen reversed.
  180.  
  181.   (See also : SetWorkPage)
  182.  
  183.  
  184. * PutClip
  185. ---------
  186. Name        : PutClip
  187. Declaration : Procedure PutClip (var pict   : array of byte;
  188.                                  x, y, w, h : integer);
  189.  
  190.   This procedure puts an image on the specified video page (page 1
  191.   2 or 0).  It puts the image at the current x/y with the specified
  192.   w and h.  The image is 'clipped' if it is drawn off the screen.
  193.   Example: If you were to use PutImage with an x value of -20, then
  194.   the image would wrap around to the opposite side of the screen.
  195.   Where as PutClip would only show the portion of the image that is
  196.   within the physical page.
  197.  
  198.   (See also : SetWorkPage)
  199.  
  200.  
  201.  
  202. * PutClipD
  203. ----------
  204. Name        : PutClipD
  205. Declaration : Procedure PutClip (var pict   : array of byte;
  206.                                  x, y, w, h : integer);
  207.  
  208.   This procedure is identical to PutClip except for an intentional
  209.   delay.  I noticed a speed difference when writing the Game_SampleDemo,
  210.   so I added this procedure.  It simulates the delay FlipClip creates
  211.   because it has to flip the image.  So when doing an animation, use this
  212.   along with your FlipClip so it will move at the same rate in either
  213.   direction.
  214.  
  215.  
  216. * FlipClip
  217. ----------
  218. Name        : FlipClip
  219. Declaration : Procedure FlipClip (var pict   : array of byte;
  220.                                   x, y, w, h : integer);
  221.  
  222.   This procedure puts an image on the specified video page (page 1
  223.   2 or 0).  It puts the image at the current x/y with the specified
  224.   w and h.  The image is drawn reversed *and* 'clipped' if it is drawn
  225.   off the screen.  Example: If you were to use PutImage with an x
  226.   value of -20, then the image would wrap around to the opposite side
  227.   of the screen.  Where as PutClip would only show the portion of the
  228.   image that is within the physical page.
  229.  
  230.   (See also : SetWorkPage)
  231.  
  232.  
  233. * PageCopy
  234. ----------
  235. Name        : PageCopy
  236. Declaration : Procedure PageCopy (sourcePage, destPage : byte);
  237.  
  238.   This procedure copies "sourcePage" to the "destPage".  Both
  239.   values ranges are from 1-4.
  240.  
  241.  
  242. * ShowPage
  243. ----------
  244. Name        : ShowPage
  245. Declaration : Procedure ShowPage (vpage : word);
  246.  
  247.   This procedure displays the specified video page.
  248.  
  249.  
  250. * SetWorkPage
  251. -------------
  252. Name        : SetWorkPage
  253. Declaration : Procedure SetWorkPage (vpage : byte);
  254.  
  255.   This procedure sets the current work page.  PutImage, FlipImage,
  256.   PutClip, FlipClip, VPrint, FontPrint, PutPixel, and ClearScreen.
  257.  
  258.   Example:
  259.           SetWorkPage (1);
  260.           PutImage (cel1^, 100, 100, 25, 25);
  261.  
  262.           * this would "Put" an image on Page 1 of the video page.
  263.  
  264.  
  265.  
  266. * GetWorkPage
  267. -------------
  268. Name        : GetWorkPage
  269. Declaration : Function GetWorkPage : Byte;
  270.  
  271.   This function returns the "active" video page (the page that is
  272.   currently being drawn to).
  273.  
  274.  
  275. * Update
  276. --------
  277. Name        : Update
  278. Declaration : Procedure Update;
  279.  
  280.   This procedure ties into many of the other procedures in VGFX and
  281.   using them in conjunction with one another creates an animation
  282.   "engine".  Update does this by keeping track of which video page
  283.   is currently being drawn to and which video page is currently
  284.   being displayed.  Update also does all the undrawing that needs to
  285.   be done, so the only thing you have to do is call a drawing routine
  286.   (or routines as the case may be) and an Update.  You would not use
  287.   update to display simple pictures to the screen- it is *only* used
  288.   to generate animatons.  Update should be called within a loop, this
  289.   is how it constantly keeps track of what to draw and what to show.
  290.  
  291.   Let's take a look at a basic 'Update' example:
  292.  
  293.   Var
  294.      QUIT : BOOLEAN;
  295.  
  296.      Begin
  297.          {  CODE FOR INITIALIZING THE GRAPHICS MODE, AND GRABBING
  298.             AN ANIMATION WOULD GO HERE.  LOADING A BACKGROUND SCENE
  299.             IS OPTIONAL AS WELL. }
  300.  
  301.           QUIT := FALSE;
  302.           repeat
  303.                 {  ANY ANIMATIONS TO BE DONE ARE CALLED ANYWHERE IN
  304.                    THE LOOP BEFORE THE UPDATE PROCEDURE }
  305.                 PutImage(AnimationCel^, x, y, 25, 25);
  306.  
  307.                 { UPDATE WILL DRAW ALL CURRENT ANIMATIONS TO THE
  308.                   HIDDEN PAGE, THEN 'FLIP' TO THAT PAGE (I.E MAKE IT
  309.                   VISIBLE). }
  310.                 Update;
  311.  
  312.                 if (keypressed) then
  313.                 begin
  314.                   key := UpCase(readkey);
  315.                   if (key = 'Q') then QUIT := TRUE;
  316.  
  317.                   { KEYBOARD CONTROLS FOR SPRITES COULD BE ADDED TO
  318.                     HERE }
  319.                 end;  { if\then }
  320.           until (QUIT = TRUE);
  321.  
  322.  
  323.  
  324.   We designed VGFX around the Update procedure.  You do not have to
  325.   use the Update procedure - it will just make your life a HELL of a
  326.   lot easier!  If you do not use Update you will have to keep track
  327.   of all current animations, on both pages.  You will have to store
  328.   all of the background information and restore every time the
  329.   animation changes position.
  330.  
  331.   * SEE MOUSE ROUTINE: MINIT
  332.         - Mouse routines are included in VGFX.  They were also
  333.           designed around Update.  I am drawing the mouse cursor, not
  334.           the driver, so if you do not use Update (and are generating
  335.           animations on your own) and wish to use the mouse then you
  336.           will have to save the background behind it as well- just as
  337.           you would for a sprite animation.
  338.  
  339.  
  340.   Update uses page 4 to constantly redraw the "static" background.
  341.   If you "put" any data to page 4, then that data will become part
  342.   of the background.  This is usefull if something must change 1 time;
  343.   if it is to change anymore than that it would probably be best to draw
  344.   it as an animation.  A good example would be in an RolePlaying type
  345.   game.  If your guy picks up a dagger that is laying on the ground,
  346.   then the dagger will need to disappear after it has been picked up.
  347.   So instead of constantly drawing the dagger as an animation it would
  348.   be more applicable to have that tiny portion of the background saved
  349.   (once with the dagger, once without the dagger), so that when the
  350.   guy picks the dagger up, just that portion of the background is
  351.   restored (picture w/out the dagger).
  352.  
  353.  
  354.   (SEE GUYDEMO.EXE & GUYDEMO.PAS)
  355.   GUYDEMO.PAS was written to show you the difference between using
  356.   the Update procedure for "page-flipping" animations and programming
  357.   the "page-flips" manually.  As you will see the Update engine is
  358.   running much slower than the manual engine.  This is because Update
  359.   is redrawing the whole screen to keep the background updated.  By
  360.   manually keeping track of the "page-flips" you achieve a lot faster
  361.   animation.  The disadvantage to manually "page-flipping" is that a
  362.   lot more programming is required.  If you are using VGFX and
  363.   writing a game that requires a 486SX-20 or better, than I would
  364.   suggest using Update.  If your game requires a 386SX or better than
  365.   you may want to use manual "page-flipping".  Another disadvantage
  366.   to manual "page-flipping" is that some routines in VGFX do support
  367.   the manual method.  For example, the mouse routines.  Although you
  368.   can use MShow and MPress, MMove will not work.  If you call MMove
  369.   without Update, the mouse will leave "trails" behind.  You will have
  370.   to keep track of that on your own.  This may seem like a bit of a
  371.   drag, but if you have already figured out the code for manually
  372.   updating your game sprites (animations) then you can easily use the
  373.   same method on the mouse cursor.  The are two global variables in
  374.   VGFX, mX and mY.  These two variables are the current mouse coords.
  375.   We would suggest creating two var's: lastX and lastY.  Here is some
  376.   theory on to as how you could do that.  We have not tested but it
  377.   seems straightforward.
  378.  
  379.  
  380.  
  381.   *** THEORY ***
  382.   ==============
  383.  
  384.   mX = 10
  385.   mY = 10
  386.  
  387.   lastX = mX
  388.   lastY = mY
  389.  
  390.   start of the loop
  391.  
  392.         Undraw the mouse cursor
  393.  
  394.         MMove is called - this gets the new mouse position
  395.           * New Mouse position was calculated by MMove. mX and mY
  396.             both equal the new mouse position (if it was moved).
  397.  
  398.         lastX = mX
  399.         lastY = mY
  400.  
  401.   end of loop
  402.  
  403.  
  404. * UpdatePalette
  405. ---------------
  406. Name        : UpdatePalette
  407. Declaration : Procedure UpdatePalette (SyncOn : byte);
  408.  
  409.   This procedure updates the current palette.  The palette is held in
  410.   an array called pal (pal : array[1..768] of byte).  The information
  411.   is stored as: r,g,b, r,g,b, r,g,b etc.  I have left this array
  412.   global in case anyone needs to play around with the palettes.
  413.  
  414.  
  415. * RestorePalette
  416. ----------------
  417. Name        : RestorePalette
  418. Declaration : Procedure RestorePalette;
  419.  
  420.   This restores the current palette to a previously loaded one.  When
  421.   you load a .PCX or .BMP you have the option of using the current
  422.   palette or loading the palette that was saved in the picture file.
  423.   If you choose to use the current palette, a spare copy of the
  424.   picture files palette is also saved.  For example:
  425.  
  426.   BlankPalette;                -> Blacks out the current palette
  427.   showpcx ('frac.pcx', 1, 1);  -> this uses the current palette when
  428.                                   displaying the picture, and draws
  429.                                   it on page 1.  It also saves a copy
  430.                                   of the palette stored in the PCX
  431.                                   file.
  432.  
  433.   FadeIn (1, 1, 0);            -> You could do this fades the palette
  434.                                   from Black to the original colors of
  435.                                   the PCX file.
  436.  
  437.   RestorePalette;              -> You could do this to instantly load
  438.                                   the palette from black to color!
  439.  
  440.  
  441.  
  442. * FadeOut
  443. ---------
  444. Name        : FadeOut
  445. Declaration : Procedure FadeOut (Step, SyncOn, DTime : byte);
  446.  
  447.   This procedure fades the current palette to black.  Step is the
  448.   amount the palette is decremented with each fade.  A step rate of
  449.   one will slowly fade the palette to black- this is a standard
  450.   fading effect used in many games.  A step rate of five will quickly
  451.   fade the palette to black.  SyncOn determines whether or not the
  452.   palette update will be synchronized to the vertical retrace.
  453.   Syncing creates a very *SMOOTH* fading effect (see DEMO.PAS).
  454.   DTime is the fading delay in milliseconds.  If you are syncing to
  455.   the vertical retrace then you probably will not want a delay,
  456.   therefore you should pass a value of zero.
  457.  
  458.  
  459. * FadeOutStep
  460. -------------
  461. Name        : FadeOutStep
  462. Declaration : Procedure FadeOutStep (Step, SyncOn, DTime : byte);
  463.  
  464.   This procedure fades out the palette one pass at a time.  This
  465.   allows you to slowly fade the screen within a loop.  (See DEMO.PAS)
  466.  
  467.   See FadeOut for parameter information.
  468.  
  469.  
  470. * FadeIn
  471. --------
  472. Name        : FadeIn
  473. Declaration : Procedure FadeIn (Step, SyncOn, DTime : byte);
  474.  
  475.   This procedure fades a palette from black to color.
  476.  
  477.   See FadeOut for parameter information.
  478.  
  479.  
  480. * FadeStepIn
  481. ------------
  482. Name        : FadeStepIn
  483. Declaration : Procedure FadeStepIn (Step, SyncOn, DTime : byte);
  484.  
  485.   This procedure fades the palette in one pass at a time.  This
  486.   allows you to slowly fade the screen within a loop.  (See DEMO.PAS)
  487.  
  488.   See FadeOut for parameter information.
  489.  
  490.  
  491. * BlankPalette
  492. --------------
  493. Name        : BlankPalette
  494. Declaration : Procedure BlankPalette;
  495.  
  496.   This procedure quickly sets all the palettes to black (thus
  497.   blanking the screen out).
  498.  
  499.  
  500.  
  501. * SetRGB
  502. --------
  503. Name        : SetRGB
  504. Declaration : SetRGB (color, r, g, b : byte);
  505.  
  506.   This procedure is used to set the RGB of a specific color.
  507.  
  508.  
  509. * ShowPcx
  510. ---------
  511. Name        : ShowPCX
  512. Declaration : Function ShowPcx (FileName  : String; PalOptions,
  513.                                 WhichPage : byte) : Integer;
  514.  
  515.   This procedure loads a PCX image from disk.  You can load the image
  516.   to the screen or just load it into memory.  FileName is the name of
  517.   the PCX file to load.  If PalOptions is set to 0 then the palette
  518.   from that PCX file is loaded, if it is set to 1 then the palette
  519.   from the PCX file is loaded into memory, but the current palette is
  520.   not modified.  WhichPage determines which video page the picture is
  521.   displayed to.
  522.  
  523.   When an image is loaded through ShowPCX it is automatically loaded
  524.   to page 4.  Page 4 is the background buffer for the update
  525.   procedure.
  526.  
  527.   (See Update)
  528.  
  529.   If the file loaded without problems then ShowPcx returns 0
  530.   otherwise:
  531.             -1  : is not a valid PCX file
  532.             -2  : the PCX is a wrong format (i.e. 16 color picture)
  533.                   * ShowPCX only loads 256 color 320x200 images.
  534.  
  535.   If ShowPcx returns a value greater than 0 this indicated a disk
  536.   error (See IOResult in your Pascal manual for error descriptions).
  537.  
  538.  
  539.  
  540. * ShowBmp
  541. ---------
  542. Name        : ShowBMP
  543. Declaration : Function ShowBmp (FileName  : String; PalOptions,
  544.                                 WhichPage : Byte) : Integer;
  545.  
  546.   This procedure loads a BMP image from disk.  You can load the image
  547.   to the screen or just load it into memory.  FileName is the name of
  548.   the BMP file to load.  If PalOptions is set to 0 then the palette
  549.   from that BMP file is loaded, if it is set to 1 then the palette
  550.   from the BMP file is loaded into memory, but the current palette is
  551.   not modified.  WhichPage determines which video page the picture is
  552.   displayed to.
  553.  
  554.   When an image is loaded through ShowBMP it is automatically loaded
  555.   to page 4.  Page 4 is the background buffer for the update
  556.   procedure.
  557.  
  558.   (See Update)
  559.  
  560.  
  561.   If the file loaded without problems then ShowBmp returns 0
  562.   otherwise:
  563.             -1  : Not a valid BMP file (must be windows 3.x BMP).
  564.                   (Note: Cannot be in compressed format).
  565.  
  566.             -2  : Possible corrupt BMP file.
  567.  
  568.             -3  : Invalid image size (i.e. the image is 0x0 pixels).
  569.  
  570.             -4  : Not a 256 color picture. (i.e. it's monochrome).
  571.                   * ShowBMP only loads 256 color 320x200 images.
  572.  
  573.             -5  : BMP is compressed (must be in uncompressed format).
  574.  
  575.  
  576.   If ShowBMP returns a value greater than 0 this indicated a disk
  577.   error (See IOResult in your Pascal manual for error descriptions).
  578.  
  579.  
  580. * MakeBMP
  581. ---------
  582. Name        : MakeBMP
  583. Declaration : Function MakeBMP (FileName      : string;
  584.                                 width, height : integer) : Integer;
  585.  
  586.   Saves the current page as a BMP file to disk as a Windows 3.x
  587.   compatible, uncompressed, 320x200x256 color bitmap.
  588.  
  589.   If ShowBMP returns a value of 0 then the file was successfully
  590.   saved.  Otherwise there was a disk error (See IOResult in your
  591.   Pascal manual for error descriptions).
  592.  
  593.  
  594.  
  595. * VGFX MOUSE ROUTINES
  596. =====================
  597.  
  598.  
  599. * MInit
  600. -------
  601. Name        : MInit
  602. Declaration : Function MInit : byte;
  603.  
  604.   This function initializes the mouse driver and allows you to easily
  605.   incorporate mouse input via the Update procedure (See Update).
  606.   If MInit returns a -1 then either no mouse or driver was detected,
  607.   otherwise MInit returns the number of buttons on the mouse.
  608.  
  609.  
  610. * MShow
  611. -------
  612. Name        : MShow
  613. Declaration : Procedure MShow (visible : byte);
  614.  
  615.   If visible equals 1 then the mouse is displayed, if it is set to 0
  616.   then the mouse is hidden.
  617.  
  618.  
  619. * MMove
  620. -------
  621. Name        : MMove
  622. Declaration : Procedure MMove;
  623.  
  624.   The routine is used in conjunction with Update.  It reads in the
  625.   mouse position and moves the cursor respectively.
  626.  
  627.  
  628. * MClick
  629. --------
  630. Name        : MClick
  631. Declaration : Procedure MClick (which_btn : integer);
  632.  
  633.   This routine reads the mouse button clicks since the last check.
  634.   If which_btn = 0 then button one is returned
  635.                = 1 then button two is returned
  636.                = 2 then the center button is returned (on 3 btn mice)
  637.  
  638.   The button information is returned to 3 global variables.
  639.   BtnP - 0 if the button hasn't been pressed since last call, or the
  640.          number of clicks since you last checked for button clicks
  641.   btnX - the X position of the mouse cursor at the time of the last click
  642.   btnY - the Y position of the mouse cursor at the time of the last click
  643.  
  644.  
  645. * MPress
  646. --------
  647. Name        : MPress
  648. Declaration : Procedure MPress (Btn1, Btn2, Btn3 : Boolean);
  649.  
  650.   This routine reads the mouse button state.
  651.   If Btn1 is true then button one is pressed
  652.   If Btn2 is true then button two is pressed
  653.   If Btn3 is true then the center button is pressed (on 3 btn mice)
  654.  
  655.  
  656.  
  657. * SetHotSpot
  658. ------------
  659. Name        : SetHotSpot
  660. Declaration : Procedure SetHotSpot (x, y : integer);
  661.  
  662.   The procedure sets the HotSpot of the mouse.  The HotSpot is the
  663.   pixel position (within the cursor) that returns x and y to
  664.   btnX and btnY, when a button is clicked.
  665.  
  666.  
  667. * SetCursorShape
  668. ----------------
  669. Name        : SetCursorShape
  670. Declaration : Procedure SetCursorShape (MouseData : array of byte);
  671.  
  672.   This procedure makes any 16 x 16 graphic the current mouse cursor.
  673.   Palette position #255 is the "transparent" color.  An image can be
  674.   loaded from screen or disk into an array.  If you need to load an
  675.   image from the screen call the GetImage function.
  676.  
  677.  
  678.  
  679. * VGFX JOYSTICK ROUTINES
  680. ========================
  681.  
  682.  
  683. * Init_Joy
  684. ----------
  685. Name        : Init_Joy
  686. Declaration : Functon Init_Joy : Boolean;
  687.  
  688.   You need to call this procedure before you can use VGFX's joystick
  689.   routines.  The function returns false if the joystick was not
  690.   found.
  691.  
  692.  
  693. * GetJoy
  694. --------
  695. Name        : GetJoy
  696. Declaration : Procedure GetJoy (var Left, Right, Up, Down,
  697.                                     Btn1, Btn2, Btn3, Btn3 : Boolean);
  698.  
  699.   This procedure returns a TRUE or FALSE to variables passed.  The
  700.   names of the variable describe it all.  If only a couple variable
  701.   are needed you will need to use a junk variable.  For example:
  702.  
  703.       GetJoy (jLeft, jRight, jUp, JUNK, jBtn1, JUNK, JUNK, JUNK);
  704.  
  705.  
  706.  
  707. * VGFX FONT ROUTINES
  708. ====================
  709.  
  710.  
  711. * VPrint
  712. --------
  713. Name        : VPrint
  714. Declaration : Procedure VPrint (theText : string; x, y : integer;
  715.                                 color, bkgrnd : byte);
  716.  
  717.   This procedure prints text using the (standard) BIOS font.  It
  718.   prints "theText" at the specified x/y position, using the
  719.   color and bkgrnd (background).
  720.  
  721.  
  722. * LoadFont
  723. ----------
  724. Name        : LoadFont
  725. Declaration : Function LoadFont (FileName : string;
  726.                        FontNum : longint) : Boolean;
  727.  
  728.   This function loads a font from the 'fonts.bin' file.  There are
  729.   31 fonts in all to choose from.  The FileName should specify
  730.   'fonts.bin' (although there are no other bin files to choose from at
  731.   this time, others may be available in the future).  FontNum
  732.   specifies the font you want to use.  The fonts are numbered 0 to 30.
  733.  
  734.   (See VGFX.INC for a listing of all the font names, which are stored
  735.    in a constant for your use).
  736.  
  737.  
  738. * FontStyle
  739. -----------
  740. Name        : FontStyle
  741. Declaration : Procedure FontStyle (Underline, Italic,
  742.                                    DoubleWide, DoubleHigh : Boolean);
  743.  
  744.   This procedure determines which style the fonts will be printed
  745.   with.  If Underline is TRUE then it prints the font underlined, if
  746.   Italic is TRUE then it prints the font in italics, etc. etc.
  747.   Any number of combinations will work.  For example:
  748.  
  749.   FontStyle (TRUE, FALSE, FALSE, FALSE);  --> PRINTS FONT UNDERLINED
  750.  
  751.   FontStyle (TRUE, FALSE, FALSE, TRUE);   --> PRINTS FONT UNDERLINED &
  752.                                               DOUBLEHIGH
  753.  
  754.   FontStyle (FALSE, TRUE, TRUE, FALSE)    --> PRINTS FONT IN ITALICS &
  755.                                               DOUBLEWIDE
  756.  
  757.  
  758.  
  759. * FontPrint
  760. -----------
  761. Name        : FontPrint
  762. Declaration : Procedure FontPrint (theText : string; x, y : integer;
  763.                                    color   : byte);
  764.  
  765.   The procedure prints a font to the screen, using the specified font
  766.   (see LoadFont) in the specified style (see FontStyle).  It prints
  767.   "theText" at the x/y parameters in the specified color.
  768.  
  769.   * A NOTE ABOUT FONTS:
  770.     Although we have provided you with 31 built in fonts, you may have
  771.     need for a font that isn't there.  It is possible to generate a
  772.     font as an image (i.e. draw a font in a graphics program) and
  773.     save it as a PCX file.  You can then load that image using ShowPCX
  774.     and grab the fonts using GetImage.  A type could be created to
  775.     hold the font data.
  776.  
  777.     Type
  778.         FChar  = array[1..20, 1..16] of byte; { HOLDS EACH CHARACTER }
  779.         MyFont = record
  780.                { ARRAY POSITIONS CORRESPOND TO THEIR ASCII VALUES }
  781.                Letters : array[0..255] of FChar;
  782.         end;  { record }
  783.  
  784.     Var
  785.        { YOU WILL WANT TO ALLOCATE THE SPACE ON HEAP! }
  786.        CoolFont : ^MyFont;
  787.  
  788.  
  789.     { - - - - - - }
  790.     Procedure DrawMyFont (theText : string; x, y : integer; color : byte);
  791.     var
  792.        tmp     : byte;
  793.  
  794.     Begin
  795.          for tmp := 1 to length(theText) do
  796.          begin
  797.               PutImage (CoolFont.Letters[ord(theText[tmp])]^, x, y, color);
  798.  
  799.               { SIZE OF CHAR IN PIXELS IS 20 WIDE }
  800.               x := x + 22;
  801.          end;  { for\do }
  802.     End;  { Procedure }
  803.  
  804.     { = = = = = = }
  805.     Begin
  806.       { INIT THE GRAPHICS MODE, LOAD THE IMAGE, GRAB YOUR NEW FONT! }
  807.  
  808.       DrawMyFont ('Hello', 100, 100, 09);
  809.     End;
  810.  
  811.  
  812.     This code is basically what you would need for creating user
  813.     defined fonts.  I have not checked for optimizations and have not
  814.     tested the code, but it seems straight forward enough!
  815.  
  816.  
  817.  
  818. * VGFX SOUND ROUTINES
  819. =====================
  820.  
  821.  
  822. * SB_Init
  823. ---------
  824. Name        : SB_Init
  825. Declaration : Function SB_Init (IRQ, DMAChannel : byte;
  826.                                          BaseIO : word) : Boolean;
  827.  
  828.   Initializes the SoundBlaster VOiCe playing engine & soundcard.
  829.   This routine needs to be called only once at the begining of your
  830.   program to use the VOC playing routines, if you do not want sound
  831.   support, then simply don't call this function.  "IRQ" is the
  832.   soundcard's IRQ number.  "DMA" is the DMA channel of the soundcard
  833.   and "BaseIO" is the baseport address of the soundcard.  This function
  834.   returns a TRUE if all was successful, FALSE if there was no sound
  835.   card, or someother error.
  836.  
  837.   * NOTE:  This routine first checks for the "BLASTER" environment
  838.            variable.  If it finds this, the routine will attempt to
  839.            use those settings to initialize the soundcard.  If that
  840.            should fail, then it will attempt to use the parameters
  841.            you pass.
  842.  
  843.  
  844. * LoadVoc
  845. ---------
  846. Name        : LoadVoc
  847. Declaration : Function LoadVoc (vocname : string) : Boolean;
  848.  
  849.   This routine loads a VOC file into memory for play.  "vocname"
  850.   is the filename of the VOC file to play.  If memory could not be
  851.   allocated or the soundcard was not initialized properly with
  852.   SB_Init then this routine will return a FALSE.  Otherwise it
  853.   will return TRUE.
  854.  
  855.   * NOTE:  These routines support 1-44khz sampling rates.  But
  856.            they do not support 16-bit or stereo as of yet.
  857.            (Also, the highest sampling rate you can use is determined
  858.             by the soundcard installed in the system.  For example, if
  859.             you have a SoundBlaster 16 then you can play upto 44khz
  860.             files, but if you have a regular SoundBlaster than you can
  861.             only play upto 11khz files)
  862.  
  863.  
  864. * PlayVoc
  865. ---------
  866. Name        : PlayVoc
  867. Declaration : Procedure PlayVoc;
  868.  
  869.   This plays the currently loaded VOC file.  If you use PlayVoc after
  870.   a VOC has been "paused", then it will start playing the VOC from the
  871.   the beginning of the file.
  872.  
  873.   (See LoadVoc)
  874.  
  875.  
  876.  
  877. * PauseVoc
  878. ---------
  879. Name        : PauseVoc
  880. Declaration : Procedure PauseVoc;
  881.  
  882.   This procedure pauses the VOC that is currently being played.  If
  883.   you call PlayVoc after a VOC has been paused, then it will start
  884.   playing from the beginning of that VOC.  If you call ResumeVoc then
  885.   the VOC will start playing from the position that it was paused at.
  886.  
  887.  
  888. * ResumeVoc
  889. -----------
  890. Name        : ResumeVoc
  891. Declaration : Procedure ResumeVoc
  892.  
  893.   This procedure is used after you call PauseVoc;  Calling ResumeVoc
  894.   will start playing the VOC from the position that it was paused at.
  895.  
  896.  
  897. * LoopVoc
  898. ---------
  899. Name        : LoopVoc
  900. Declaration : Procedure LoopVoc (LoopV : Boolean; Wait : LongInt);
  901.  
  902.   When LoopV is set to TRUE, then the currently loaded VOC will play
  903.   continually, looping back around as it reaches the end of the file.
  904.   The looping is transparent to the programmer.  To disable looping
  905.   just set LoopV to FALSE.  "Wait" is the period to wait before
  906.   starting the song over again, it is measured in "clock ticks".
  907.   Clock ticks happen every 18.2 times a second, so for example,
  908.   to delay the song repeat by 2 seconds you'd specify a value of
  909.   "36".
  910.  
  911.   * NOTE:  If your program is timing-sensitive then you may want
  912.            to leave VOC looping off, as it chains an interrupt
  913.            to monitor the VOC status and restart the loop.
  914.            Also, VOC looping works outside of you program as
  915.            well, like, for instance; in a DOS shell, if you
  916.            do not call LoopVOC(false,0) before shelling then
  917.            the sound will continue to play & loop!
  918.  
  919.  
  920. * IsVocPlaying
  921. --------------
  922. Name        : IsVocPlaying
  923. Declaration : Function IsVocPlaying : Boolean;
  924.  
  925.   This function simply returns TRUE if a VOC is currently playing and
  926.   FALSE is there is no VOC playing.
  927.  
  928.  
  929.  
  930. * VGFX GLIB ROUTINES
  931. ====================
  932.  
  933.  
  934. * SetWorkLib
  935. ------------
  936. Name        : SetWorkLib
  937. Declaration : Function SetWorkLib(LibName : String) : Boolean;
  938.  
  939.   This function sets the "library" for the VGFX routines to use.
  940.   All of VGFX's routines support this "library" mode.  "LibName"
  941.   is the name of the GLIB library to use, passing a null will
  942.   disable library usage and return to regular disk access.
  943.   SetWorkLib will return a TRUE if all was successful, otherwise
  944.   FALSE will be returned.  (FALSE usually means file not found)
  945.  
  946.   Please see 'Appendix A' for more information about these features.
  947.  
  948.  
  949. * LoadLib
  950. ---------
  951. Name        : LoadLib
  952. Declaration : Function LoadLib(FileName : String; var Data; SeekPos : LongInt;
  953.                                Bytes    : Word;) : Word;
  954.  
  955.   This function loads data from a file stored in a library.
  956.   "FileName" is the name of the file within the library to load the
  957.   data from.  "Data" is any variable in which to put the loaded data
  958.   into.  "SeekPos" is the position in the file (the file within the
  959.   library) at which to begin loading, you can use "SeekPos" to seek to
  960.   any given position in the file. "Bytes" is the number of bytes to load
  961.   in from that file.  LoadLib returns a word value, it contains the actual
  962.   bytes read in, if set to 0 than an error occured.
  963.  
  964.   (See SetWorkLib and Appendix A)
  965.  
  966.  
  967.  
  968. * VGFX EMS ROUTINES
  969. ===================
  970.  
  971.  
  972. * EMS_Init
  973. ----------
  974. Name        : EMS_Init
  975. Declaration : Function EMS_Init : Word;
  976.  
  977.   Initializes the EMS driver & routines.  This must be called before you
  978.   can use the EMS routines, if not your system will hang.  EMS_Init
  979.   returns the EMS driver version, 0 if no driver was installed/found
  980.   or an error occured.  (The error code is held in EMSResult)
  981.  
  982.  > EMS1.PAS and EMSDEMO.PAS are example programs which use the EMS routines. <
  983.  
  984.   * NOTE:  These routines work with a LIM EMS v3.00 or later EMS driver.
  985.  
  986.  
  987. * EMSPage
  988. ---------
  989. Name        : EMSPage
  990. Declaration : Function EMSPage( Page : byte ) : BytePtr;
  991.  
  992.   This function returns a pointer to the physcial page specified.
  993.   ("Page" is 0-3 in range, for a total of 4 pages)
  994.  
  995.   (See Appendix B for more information on EMS; Also see EMSPageOfs)
  996.  
  997.  
  998. * EMSPageOfs
  999. ------------
  1000. Name        : EMSPageOfs
  1001. Declaration : Procedure EMSPageOfs( Offset : word );
  1002.  
  1003.   This function sets the offset in the page for EMSPage to begin
  1004.   at, thus making EMSPage return a pointer at the offset in the physcial
  1005.   page.  See EMSDEMO2.PAS for example code.
  1006.  
  1007.   (See Appendix B for more information on EMS)
  1008.  
  1009.  
  1010. * EMSAlloc
  1011. ----------
  1012. Name        : EMSAlloc
  1013. Declaration : Function EMSAlloc( Pages : integer ) : integer;
  1014.  
  1015.   This function allocates EMS pages for use.  "Pages" is the number
  1016.   of pages you want to allocate for you program's use.  (Each page
  1017.   contains 16384 bytes worth of data space).  EMSAlloc returns an
  1018.   integer "handle", this handle is used from now on as a reference
  1019.   to these pages you just allocated.  If EMSAlloc returns $FFFF then
  1020.   an error occurred during the allocation process, the error code is
  1021.   held in EMSResult, see Appendix B for more description on EMSResult.
  1022.  
  1023.  
  1024.  
  1025. * EMSFree
  1026. ---------
  1027. Name        : EMSFree
  1028. Declaration : Function EMSFree(Handle : integer) : boolean;
  1029.  
  1030.   Frees EMS pages allocated by EMSAlloc.  You must free the pages before
  1031.   your program exits or no other program will be able to use the memory.
  1032.   "Handle" is the handle passed by EMSAlloc.  EMSFree will return TRUE
  1033.   if the memory was released, FALSE if there was a problem.
  1034.  
  1035.   (The error code is held in EMSResult)
  1036.  
  1037.  
  1038. * EMSMap
  1039. --------
  1040. Name        : EMSMap
  1041. Declaration : Function EMSMap(Handle, LogP : integer; PhysP : byte) : boolean;
  1042.  
  1043.   EMSMap is used to map the logical allocated pages with the physical
  1044.   pages stored in the EMS page frame.  What this does is assigns the
  1045.   pages outside of the page frame into the frame for use by your program.
  1046.   "Handle" is the handle returned by EMSAlloc.  "LogP" is the logical page
  1047.   (0-the # of pages you allocated with EMSAlloc).  "PhysP" is the physical
  1048.   page in the EMS page frame.  (0-3 for a total of 4 pages at any given
  1049.   time).  This function returns TRUE if the memory was mapped correctly,
  1050.   FALSE if there was an error.
  1051.  
  1052.   (The error code is held in EMSResult)
  1053.  
  1054.  
  1055. * EMSSaveMap
  1056. ---------------
  1057. Name        : EMSSaveMap
  1058. Declaration : Function EMSSaveMap( Handle : integer ) : boolean;
  1059.  
  1060.   Saves an EMS map.  "Handle" is the handle returned by EMSAlloc.
  1061.   This saves the current EMS page frame, to be restore to normal,
  1062.   later on by EMSRestoreMap.  This function returns TRUE if the map
  1063.   was restored, FALSE if there was an error.
  1064.  
  1065.   (The error code is held in EMSResult)
  1066.  
  1067.  
  1068. * EMSRestoreMap
  1069. ---------------
  1070. Name        : EMSRestoreMap
  1071. Declaration : Function EMSRestoreMap( Handle : integer ) : boolean;
  1072.  
  1073.   Restores a saved EMS map.  "Handle" is the handle returned by
  1074.   EMSAlloc.  This function returns TRUE if the map was restored,
  1075.   FALSE if there was an error.
  1076.  
  1077.   (The error code is held in EMSResult; See also EMSSaveMap)
  1078.  
  1079.  
  1080.  
  1081. * EMSPages
  1082. ----------
  1083. Name        : EMSPages
  1084. Declaration : Function EMSPages : integer;
  1085.  
  1086.   This function returns the total amout of EMS pages that the EMS
  1087.   driver had allocated.  (Not the free available pages to your
  1088.   program, see below)
  1089.  
  1090.  
  1091. * EMSFreePages
  1092. --------------
  1093. Name        : EMSFreePages
  1094. Declaration : Function EMSFreePages : integer;
  1095.  
  1096.   This function returns the total amount of free EMS pages. (meaning
  1097.   these pages are available NOW for your program to use).
  1098.  
  1099.  
  1100. * MkPtr
  1101. --------------
  1102. Name        : MkPtr
  1103. Declaration : Function MkPtr (var variable) : Pointer;
  1104.  
  1105.   This function creates a pointer to the specified variable.  I added
  1106.   this routine for convenience, it is just "ptr(seg(xx),ofs(xx))" being
  1107.   returned via this function, but it makes creating and using pointers
  1108.   easier.  See EMS1.PAS for an example on how to use it.
  1109.  
  1110.  
  1111.  
  1112.  
  1113. * VGFX MISC. ROUTINES
  1114. =====================
  1115.  
  1116.  
  1117. * Int2Str
  1118. ---------
  1119. Name        : Int2Str
  1120. Declaration : Function Int2Str (Num : LongInt) : String;
  1121.  
  1122.   This function converts and integer value into a string and then
  1123.   returns the string.
  1124.  
  1125.  
  1126. * Exist
  1127. -------
  1128. Name        : Exist
  1129. Declaration : Function Exist (FileName : string) : boolean;
  1130.  
  1131.   This function checks to see if a file exists or not.  "FileName"
  1132.   is the filename/path of the file you want to check for.  Example:
  1133.  
  1134.      if (Exist('C:\VGFX\VGFX.TPU')) then
  1135.         writeln('You have VGFX!');
  1136.  
  1137.  
  1138. * GetBit
  1139. --------
  1140. Name        : GetBit
  1141. Declaration : Function GetBit (Bytes : byte; Bit : byte) : boolean;
  1142.  
  1143.   This function Checks to see if the specified bit is set to true.
  1144.   "Bytes" is the value you want to test for bit settings. "Bit" is
  1145.   a range from 0 to 7 (7 is bit 8) of the bit you want to check.
  1146.   GetBit will return a TRUE if the bit is set, FALSE if not.
  1147.  
  1148.  
  1149. * BitSet
  1150. --------
  1151. Name        : BitSet
  1152. Declaration : Function BitSet (n     : byte; bit : byte;
  1153.                                state : boolean) : byte;
  1154.  
  1155.   Sets or releases a specific bit in a byte.  "n" is the byte
  1156.   to pass.  "bit" is the bit to set/release (0-7).  "state" is
  1157.   the state of the bit (TRUE=ON (1), FALSE=OFF (0)).
  1158.  
  1159.  
  1160. * StrUpCase
  1161. -------
  1162. Name        : StrUpCase
  1163. Declaration : Function StrUpCase (St : string) : string;
  1164.  
  1165.   This function converts "St" to all capital letters and then is
  1166.   returned.
  1167.  
  1168.  
  1169.  
  1170. * StrLCase
  1171. -------
  1172. Name        : StrLCase
  1173. Declaration : Function StrLCase (st : string) : string;
  1174.  
  1175.   This function converts "St" to all lowercase letters and then is
  1176.   returned.
  1177.  
  1178.  
  1179. * CopyFile
  1180. ----------
  1181. Name        : CopyFile
  1182. Declaration : Function CopyFile (infile, outfile : string) : boolean;
  1183.  
  1184.   Copies files from source to dest.  "source" is the source filename
  1185.   and "dest" is the destination filename.  Example:
  1186.  
  1187.      CopyFile ("C:\TEST1.EXE", "D:\TEMP\TEST1.EXE");
  1188.  
  1189.   This function returns TRUE if the file was copied, FALSE if not.
  1190.   (You can use IOResult to see the specific error, see your Pascal
  1191.    manual.)
  1192.  
  1193.  
  1194. * SubExist
  1195. ----------
  1196. Name        : SubExist
  1197. Declaration : Function SubExist (pathname : string) : boolean;
  1198.  
  1199.   Checks to see if a subdirectory on the drive exists or not,
  1200.   "pathname" is the path including drive letter (i.e.- "C:\TEMP").
  1201.   This function will return TRUE if the directory is found FALSE
  1202.   if not.
  1203.  
  1204.  
  1205. * FlushKB
  1206. ---------
  1207. Name        : FlushKB
  1208. Declaration : Procedure FlushKB;
  1209.  
  1210.   Flushes the keyboard buffer.  Empty's out any waiting characters.
  1211.  
  1212.  
  1213.  
  1214.  
  1215. * APPENDIX A:  GLIB Utility
  1216. ===========================
  1217.  
  1218. What is GLIB??  GLIB is a "LIB" utility that allows you to store all
  1219. kinds of files together in one massive database (refered to as 'library'
  1220. from here-in).  GLIB's command line arguments are almost identical to
  1221. those of any standard "LIB" utility.  These libraries can only be created/
  1222. modified by the GLIB utility, but files within these libraries are
  1223. accessed via VGFX's routines like LoadVOC, ShowBMP, ShowPCX, etc. or they
  1224. can be accessed via the 'LoadLib' function.  LoadLib allows you to load
  1225. any amount of data from any position within the file contained in the lib.
  1226.  
  1227. Now, to create a library you need to use the GLIB utility included with
  1228. your VGFX package, this utility takes the following command-line arguments:
  1229.  
  1230.      GLIB Libname [options][File1] [File2] [File3..]
  1231.  
  1232. If you run GLIB with just the name of a library it will list the contents of
  1233. the library file to the screen with "more" prompts.  Options are as follows:
  1234.  
  1235.  -+      Update; Updates a file that already exists in the library,
  1236.                  this function is useful for updating modifications
  1237.                  to certain files contained within the library.
  1238.  
  1239.  *      Extract; Extracts a COPY of a file contained in the library to
  1240.                  disk.  This function will NOT REMOVE a file from the
  1241.                  library, it only extracts a COPY of the file to disk.
  1242.  
  1243.  -       Remove; Remove deletes a copy of a file contained in the library.
  1244.                  This function does not make a copy on disk before removing
  1245.                  the file from the library, so make sure you have a copy
  1246.                  already if you want to save it!  Once you call this
  1247.                  option it will remove all the files specified on the cmd-
  1248.                  line.
  1249.  
  1250.  +   Add/Create; Add will add files to a library or create a library if
  1251.                  there is no existing library already.
  1252.  
  1253.  
  1254. * Tech stuff:
  1255. GLIB limitations..  GLIB is limited to no more than 65535 files at any one
  1256.                     time in a library, also the total file size of a library
  1257.                     must not exceed 2.1gb
  1258.  
  1259.  
  1260. Well I hope that clears up any confusion on what GLIB is, I'm sure I left out
  1261. something...  Anyways, see GLIB1.PAS for an example on how to use GLIB in/with
  1262. VGFX.
  1263.  
  1264.  
  1265.  
  1266. * APPENDIX B:  More on EMS
  1267. ==========================
  1268.  
  1269. Ok, EMS memory... hmm, this outta be a tough one.  EMS memory works like
  1270. this:  You have the EMS "pages" in memory (pages are 16384 byte (16k)
  1271. blocks of memory, the driver refers to them as pages).  You can allocate
  1272. as many pages as the driver will allow for your programs usage.  EMS drivers
  1273. keep a thing called a "page-frame" or "map" in conventional memory, this map
  1274. contains four (numbered 0-3) pages in it (totaling for 64k), these are called
  1275. physical pages.  Logical pages are the other pages outside of conventional
  1276. memory.  (when you call EMSAlloc you are allocating logical pages)  In order
  1277. to access your allocated Logical pages you must move them into the EMS "page-
  1278. frame".  Doing this is called "mapping" (this is where it gets tricky :) )
  1279. What you want to do is keep the most used pages in the page-frame all the time
  1280. that way access will be fastest.  You can map your pages via the EMSMap
  1281. function in your EMS unit.  Now remember that in order to use the pages you
  1282. allocate you must move them into the page-frame.  Here is an example:
  1283.  
  1284.   handle := EMSAlloc(1);  { Get 1 page (remember your pages are numbered from
  1285.                             0 - maxpage, so allocating this one page makes it
  1286.                             logical page number 0!}
  1287.   EMSMap(handle, 0, 0);   { the first arg is the handle returned by EMSAlloc
  1288.                             the second arg is the logical page to assign
  1289.                             and the third arg is the physical page to assign
  1290.                             that logical page to. }
  1291.  
  1292. Now that we've done that, our logical page we allocated is now available in
  1293. the page-frame under physical page 0 for access.  Whew!  Well thats about
  1294. as in-depth as I can go into EMS today, but I hope this helped!
  1295.  
  1296.