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


This archive contains the second 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.  BEFORE RUNNING, PLEASE REFER
TO THE OUTSTANDING PROBLEMS SECTION!


This document
-------------
The following topics are covered by this document:

  What is is and How it works
  Problems from Beta 1 that are resolved and new features
  Outstanding items and known problems
  Using the library
  Debugging the library
  Optimising GRAPH/VP
  BETA messages
  The innards
  Example Code
  Feedback
  Buying Virtual Pascal for OS/2


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.


Problems from Beta 1 that are resolved and new features
-------------------------------------------------------
 - All drawings are now much faster.  The PM version is now quite
   fast, and the Txt version is adequately fast.

 - Floodfill has been implemented

 - Sector and Pieslice are now filled if specified

 - GetImage and PutImage are implemented for Client/Server version

 - The appearance of all drawings with ThickWidth, particularly round
   objects, are much improved

 - All reasonable resolutions supported.  Use VPInitGraph to start a window
   of any resolution using VPInitGraph( xRes, yRes, BGIFontPath )

 - Mouse support.  Similar to KeyPressed and Readkey, functions for
   querying mouse position and events are available.

 - More variables for controlling Client/Server interaction.

 - BGI font output is much faster than before

 - The 3D bars of the BGIDEMO example are now filled

 - An error message will be displayed if DIVE is not installed

 - If an old version of DIVE is used, accelerated blitting is disabled.

 - If no warning messages should be displayed, set Os2Dive.SuppressMessages
   to True.

 - Beta messages are displayed on screen when initialising.

 - This readme file has been updated


Outstanding items and known problems
------------------------------------
 - Font style/size and direction not implemented for the 8x8 default font

 - Graphics output is somewhat slower than in DOS.

 - Changing the palette on the fly is very slow

 - IMPORTANT: The shipping version of VP/2 v1.1 has an error in the
   SysUtils unit. When an exception occurs, the error handler in
   SysUtils itself causes an exception.
   To prevent this from happening, do the following:
     - Edit SYSUTILS.RC in the SOURCE\RTL directory.
       Change the SException string (line 35) by removing the last %s,
       making it read
         SException, "Exception %s in module %s at %p.\x0A%s%s"
     - Recompile SYSUTILS.RC by typing
         RC -r SYSUTILS.RC


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;

  Mouse Support
    In both versions, mouse position and events can be queried using
    the following functions:

      procedure GetMousePos( var x,y: Word );
        Returns the current position of the mouse

      function  MouseClicked: Boolean;
        Similar to keypressed; returns True, if a mouse event is waiting

      procedure GetMouseEvent( var M: MouseEventRecT );
        Similar to Readkey; waits for a mouse event and returns it.

      function  ReadKeyOrMouse( TimeOut: Word; var Mouse: Boolean;
        var Key: Char; var MEvent: MouseEventT; var mx, my: Word ): Boolean;
        Combined Readkey and GetMouseEvent function with timeout.  Waits
        for up to TimeOut milli-seconds (-1 means indefinite wait) and
        returns the next keyboard- or mouse-event.  If a mouse event
        is returned, Mouse is set to True, otherwise to False.  Mx an My
        is the position of the mouse at the time of the event.

  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.

      var ImmediateUpdate: Boolean
        When true, all commands are immediately sent to the server for
        processing; this is good for animated graphics or for debugging.
        When false, commands are queued and sent to the server in chunks.
        This gives faster processing but more "chunky" screen output.

      var MinFrameRate: Longint
        Default is 5 frames per second; this value is irrelevant if
        ImmediateUpdate is true.  Otherwise, setting this value ensures
        that the Server gets all waiting commands at least MinFrameRate
        times per second.


    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.


Debugging the library
---------------------
  When debugging programs using GRAPH, a few of the more advanced
  debugging features of VP/2 are handy.

  If you are writing a program for use with the client/server version,
  and experience traps and exceptions in the GRAPHSRV executable, you
  can do the following:

    - Insert
        Graph.AutoStartServer := False;
        Graph.WaitKeyPressed := True;
      into your code before calling InitGraph.

    - Start a new copy of the VP/PM IDE.  To make OS/2 start a new copy
      when clicking on the icon (instead of activating the already
      active copy), open the properties/settings notebook for VP/PM,
      go to the Window tab, and change "Object open behavior" to "Create
      new window".

    - In the second instance of VP/PM, load GRAPHSRV.PAS and execute it
      without any parameters.  This starts the Graph server process.

    - Switch back to the first copy of VP/PM and compile and run your
      program.

  You now have full control over both running processes.  If an exception
  occurs in either process, the relevant copy of VP/PM allows you to
  inspect variables, determine the cause of the exception, etc.

  A few options you may want to enable, depending on your specific
  problem:
    Options|Debugger menu:
      Hard PM mode - should always be on!  Without this option enabled,
      debugging Graph is likely to cause OS/2 to hang or crash.

      Break on exception - should probably be on.  When this option
      is enabled, the program being debugged does not terminate when
      an exception is raised, but instead halts execution at the
      offending instruction and allows you to inspect variables,
      parameters, call stack, etc.

    View|Exceptions dialog:
      Check XCPT_ACCESS_VIOLATION and other exceptions you experience.
      When an exception of this type is raised, the debugger immediately
      stops execution and opens the CPU window at the location of the
      error.

  Lastly, a very helpful feature is the Data Point.  To monitor the
  flow of the program, for example the position of the mouse or the
  stream of commands sent back and forth between the client and server,
  set a breakpoint at the location of interest (Ctrl-F8).  Then open
  the View|Breakpoints dialog and position the cursor on the new
  breakpoint.  Press Alt-F10 to see the local menu for the Breakpoints
  window and select "Change options...".
  In this dialog, you can change the breakpoint to be a Log Point by
  removing the check next to "Break" and set a check next to "Log".
  Enter the expressions you wish to log in the "Log expression"
  entry field, separated by semicolons, for example
    X;Y;MouseStatus
  Now, before starting execution, open the Log window (View|Log).  Every
  time your data/log point is reached, a line displaying the values
  of the Log expression is added to the Log window.


Optimising GRAPH/VP
-------------------
  DIVE is not the fastest engine for outputting graphics and cannot
  compete with full screen DOS graphics in terms of speed.  Output to
  DIVE is performed in multiple steps, where the program first requests
  access to the video buffer, then writes to it, and then tells DIVE to
  reflect the changes on the display.

  When drawing many small items on the screen, GRAPH/VP implements an
  optimising technique whereby only changed areas are updated, instead
  of always updating the entire screen.  For demo programs such as
  BGIDEMO, this accelerates the frame rate by as much as a factor of
  10, but does not come without a price.

  Early versions of DIVE (Warp without fixpacks applied) cause OS/2 to
  hang when this method is used.  Copying the DIVE.DLL from FixPak 17 or
  applying the fixpak solves the problem however, and GRAPH attempts to
  determine the current version installed during initialization.  If
  an old version is found (It simply checks the file date), the
  Os2Dive.FastBlitSupported variable is set to False and the entire
  screen is updated every time a change is made.

  In some cases, it is desirable to have this behaviour, even if the
  installed version of DIVE does support the optimised output - it
  depends on the application.  In this case, call the SlowBlit
  procedure of the Graph unit after calling InitGraph or VPInitGraph
  to disable accelerated output.


BETA messages
-------------
  When starting a program using Graph/VP, a messagebox is displayed
  on screen, either notifying of an old DIVE version or telling users
  that a beta version of GRAPH/VP has been used.

  To prevent these messages from being displayed, set the
  Os2Dive.SuppressMessages variable to True.  Error messages are
  still displayed if DIVE is not installed or cannot be initialised.


The innards
-----------
  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.


  The second example is a very simple drawing program, supplied as
  DRAW.EXE and DRAWPM.EXE.  This program illustrates how to use the
  mouse and keyboard support functions.

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.

