  London, August 1996
  ** BETA SOFTWARE **
  BGI Graphics for Virtual Pascal for OS/2 v1.1


This archive contains the first public beta version of BGI graphics for
VP/2.  Please report any problems, preferable with sample source code and
means of reproducing the error to fPrint UK as quickly as possible.

The software in this archive requires Virtual Pascal for OS/2 v1.1 and
will not work with Virtual Pascal v1.0.


What it is and How it works
---------------------------
The GRAPH unit in Borland Pascal is used to produce full-screen
graphics. In OS/2, full screen graphics are not desirable and a better
solution is available: DIVE. Using this technology, which is available
from OS/2 Warp and later, it is possible to open a window and get direct
access to video memory under OS/2.  (NOTE: Preliminary tests show that
DIVE without Warp FixPack 17 applied has serious flaws.  Please refer to
the notes below for details on this problem).

The graph unit in DOS is used in simple text-mode applications that can
be switched to graphics mode to display graphics.  In VP/2, GRAPH can be
used to make standalone graphical PM applications, or to produce apps that
combine PM and text mode using sophisticated multi-threaded background
processing.

This beta represents the initial effort to make programs written for the
GRAPH unit in DOS recompile with very few changes and run in OS/2. A few
functions are not implemented, and some functions may work slightly
differently than in Borland Pascal.


Outstanding items and known problems
------------------------------------
 - Floodfill procedure is not implemented
 - Sector and PieSlice are always displayed outlined
 - GetImage/PutImage cannot be used in combined PM/Textmode apps
 - Only VGA 640x480x256 window supported
 - Font style/size and direction not implemented for the 8x8 default font
 - Graphics output is slower than in DOS.  This library is not well
   suited for games requiring fast screen updates.
 - Changing the palette on the fly is very slow
 - A method of accelerating DIVE output is used (believe it or not),
   but this method highlights a bug in the DIVE.DLL that comes with OS/2
   Warp.  In order to use this, the DIVE.DLL needs to be at least the
   version dated september 1995 and is 123kB in size.  If you do not
   have this version, you can disable acceleration by calling SlowBlit;.
   Acceleration is enabled by calling AcceleratedBlit;


Using the library
-----------------
The library includes all standard functions of BP7's GRAPH unit and
many programs written using GRAPH will work with this version with
few or no changes.  The only change that must always be made is to
include USE32 in the Uses clause of the program.

Before beginning work with the library, UNZIP all files in this archive
to a directory on your hard disk.

  Two flavours
  ------------
  GRAPH/VP comes in two flavours.  One is for programs that mix textmode
  output with graphics (Typically a program that displays a graph or an
  illustration inbetween) and the other is for programs that are pure
  graphics (Games, for example).

  PM Version
    To use the PM only version, your program should add DGRAPH to the
    uses clause inctead of Graph.  The Linker Target should be set to
    PM, either in the Linker dialog or by entering a {$PMTYPE:PM}
    compiler directive in the code of the main program.

    Since the program is not a text-mode application, it must not use
    the Crt unit and no longer has access to the KeyPressed, Readkey,
    etc functions of that unit.  Instead, DGRAPH implements a small set
    of replacement functions that can be called instead:

      procedure Delay(MS: Longint);
      function KeyPressed: Boolean;
      function ReadKey: Char;
      function AltPressed: Boolean;
      function ShiftPressed: Boolean;
      function CtrlPressed: Boolean;

  TextMode and PM combined
    To use this version, your program should use the GRAPH unit and
    make sure that the VP/2 BGI Graphics Server, GRAPHSRV.EXE, is
    available somewhere in the PATH.

    There are no restrictions of using the Crt unit or other text-based
    units, since the program will be a text-mode application that talks
    to the PM Server Process when graphics are to be displayed.  When
    the InitGraph function is called, the Server Process is
    automatically started and the graphics output window is displayed
    alongside the text mode window of the application.

    The Server window is automatically closed when CloseGraph is
    called, or the main program terminates.

    When using applications using this interface, it is desirable to
    be able to accept rudimentary keyboard input, no matter if the text
    mode or the PM window currently have focus.  To facilitate this, the
    GRAPH unit implements two functions also declared in the Crt unit;
    these functions collect and return any keypresses detected in either
    window:

      function KeyPressed: Boolean;
      function ReadKey: Char;

  General considerations
    VP/GRAPH is very compatible with GRAPH from Borland Pascal, but
    is a complex 32-bit multi-threaded framework instead of a simple
    DOS library.

    This means that multitasking considerations need to be taken into
    account to make "good" applications.  In DOS, all graph commands are
    reflected on the output display immediately; in OS/2, a separate
    thread "blits" any changed areas to the output window at regular
    intervals.

    A few new functions are provided to accomodate multitasking:

      var WaitKeypressed: Boolean
        determines whether or not DosSleep() is called if no key is
        ready to be processed when KeyPressed is called.  This should be
        True in tight loops waiting for a keypress, like
          While not keypressed do ;
        and False if the check is used only to check whether a drawing
        loop should be exited.

    The following functions are only available in GRAPH.PAS:

      var AutoStartServer: Boolean
        determines whether or not the Graph Server should be started
        automatically.  For debugging purposes, it can be handy to
        turn this off and run GRAPHSRV from the command line or even
        to load two copies of VPPM and debug both client and server
        at the same time.

      procedure FlushDisplay;
        causes the program to wait until all changes made to the display
        since have been displayed.

    The following functions are only available in DGRAPH.PAS:

      procedure SuspendRefresh;
        can be called, if you want to draw something complex and do not
        care about it being updated regularly.

      procudure EnableRefresh;
        re-enables screen updating.

      procedure WaitDraw;
        causes the program to wait until all changes made to the display
        since have been displayed.


How it works
------------
  The combined PM/Textmode VP/GRAPH works by having a client text-mode
  application, which sends messages to a PM server process.  The server
  process, GRAPHSRV.EXE, is automatically started when InitGraph is
  called and also terminates automatically when it is no longer needed.

  This can be illustrated graphically like this:

  Component                                Function
  User application                         User code
   graph.pas                               BGI interface functions
     sends messages to Server Process

  Server Process                           Receives and parses messages
    dgraph.pas                             BGI code implementation
      Os2Dive.pas                          DIVE interface for VP/2

  For PM applications, the Server layer is not required and the
  layout is

  User application                         User code
    dgraph.pas                             BGI code implementation
      Os2Dive.pas                          DIVE interface for VP/2


Example Code
------------
  To demonstrate VP/GRAPH, this archive contains two versions of the
  BGIDEMO example from Borland Pascal, changed to Virtual Pascal.  The
  source for the examples is very similar, with only minor differences,
  and both resemble the original Borland source code as well.

  The examples are called BGIDEMO.EXE and BGIPM.EXE, respectively.
  BGIDEMO runs as a text mode application and links to the Server, which
  is started automatically.  BGIPM runs as a PM app and does not use
  the server.

  When executing the examples, please specify the full path to your
  BP7 BGI fonts, if you have them available.  Without these fonts,
  the demos will fail when trying to display Pie Charts.


Feedback
--------
  Comments, suggestions and bug reports to this beta are *very* welcome.
  You are encouraged to use and test this software extensively.  When
  we are satisfied that it works well, it will be included in the next
  version of Virtual Pascal for OS/2 and be made freely available to
  all existing customers.

  Send feedback to

    Mail:      fPrint UK Ltd
               Cambridge House
               100 Cambridge Grove
               Hammersmith
               London W6 0LE
               United Kingdom
               Att: Development

    e-mail:    vpascal@ibm.net
    Fax:       +44 181 563 2361
    BBS:       +44 181 563 8624
    www:       http://www.fprint.co.uk/vpascal


Buying Virtual Pascal for OS/2
------------------------------
  If you do not yet have a copy of Virtual Pascal for OS/2, get it quick!
  It sells for a recommended retail price of 165, or US$245 and for this
  price you get a thorough printed manual, about 30MB of files on your
  hard disk and the best Pascal development environment for OS/2.

  If you live in the US or Canada, contact NITEK Corp. for VP/2 orders:
    Anthony Busigin
    NITEK Corporation
    38 Longview CRT
    London, ON N6K 4J1
    Canada

    Tel: (519) 657-4914
    Fax: (519) 657-0283
    E-Mail: busigin@ibm.net

  For the nearest local dealer elsewhere in the world, contact fPrint UK
  on one of the above addresses or phone numbers.

