home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / vpbgib1.zip / readme.txt < prev   
Text File  |  1996-08-08  |  10KB  |  250 lines
  1.   London, August 1996
  2.   ** BETA SOFTWARE **
  3.   BGI Graphics for Virtual Pascal for OS/2 v1.1
  4.  
  5.  
  6. This archive contains the first public beta version of BGI graphics for
  7. VP/2.  Please report any problems, preferable with sample source code and
  8. means of reproducing the error to fPrint UK as quickly as possible.
  9.  
  10. The software in this archive requires Virtual Pascal for OS/2 v1.1 and
  11. will not work with Virtual Pascal v1.0.
  12.  
  13.  
  14. What it is and How it works
  15. ---------------------------
  16. The GRAPH unit in Borland Pascal is used to produce full-screen
  17. graphics. In OS/2, full screen graphics are not desirable and a better
  18. solution is available: DIVE. Using this technology, which is available
  19. from OS/2 Warp and later, it is possible to open a window and get direct
  20. access to video memory under OS/2.  (NOTE: Preliminary tests show that
  21. DIVE without Warp FixPack 17 applied has serious flaws.  Please refer to
  22. the notes below for details on this problem).
  23.  
  24. The graph unit in DOS is used in simple text-mode applications that can
  25. be switched to graphics mode to display graphics.  In VP/2, GRAPH can be
  26. used to make standalone graphical PM applications, or to produce apps that
  27. combine PM and text mode using sophisticated multi-threaded background
  28. processing.
  29.  
  30. This beta represents the initial effort to make programs written for the
  31. GRAPH unit in DOS recompile with very few changes and run in OS/2. A few
  32. functions are not implemented, and some functions may work slightly
  33. differently than in Borland Pascal.
  34.  
  35.  
  36. Outstanding items and known problems
  37. ------------------------------------
  38.  - Floodfill procedure is not implemented
  39.  - Sector and PieSlice are always displayed outlined
  40.  - GetImage/PutImage cannot be used in combined PM/Textmode apps
  41.  - Only VGA 640x480x256 window supported
  42.  - Font style/size and direction not implemented for the 8x8 default font
  43.  - Graphics output is slower than in DOS.  This library is not well
  44.    suited for games requiring fast screen updates.
  45.  - Changing the palette on the fly is very slow
  46.  - A method of accelerating DIVE output is used (believe it or not),
  47.    but this method highlights a bug in the DIVE.DLL that comes with OS/2
  48.    Warp.  In order to use this, the DIVE.DLL needs to be at least the
  49.    version dated september 1995 and is 123kB in size.  If you do not
  50.    have this version, you can disable acceleration by calling SlowBlit;.
  51.    Acceleration is enabled by calling AcceleratedBlit;
  52.  
  53.  
  54. Using the library
  55. -----------------
  56. The library includes all standard functions of BP7's GRAPH unit and
  57. many programs written using GRAPH will work with this version with
  58. few or no changes.  The only change that must always be made is to
  59. include USE32 in the Uses clause of the program.
  60.  
  61. Before beginning work with the library, UNZIP all files in this archive
  62. to a directory on your hard disk.
  63.  
  64.   Two flavours
  65.   ------------
  66.   GRAPH/VP comes in two flavours.  One is for programs that mix textmode
  67.   output with graphics (Typically a program that displays a graph or an
  68.   illustration inbetween) and the other is for programs that are pure
  69.   graphics (Games, for example).
  70.  
  71.   PM Version
  72.     To use the PM only version, your program should add DGRAPH to the
  73.     uses clause inctead of Graph.  The Linker Target should be set to
  74.     PM, either in the Linker dialog or by entering a {$PMTYPE:PM}
  75.     compiler directive in the code of the main program.
  76.  
  77.     Since the program is not a text-mode application, it must not use
  78.     the Crt unit and no longer has access to the KeyPressed, Readkey,
  79.     etc functions of that unit.  Instead, DGRAPH implements a small set
  80.     of replacement functions that can be called instead:
  81.  
  82.       procedure Delay(MS: Longint);
  83.       function KeyPressed: Boolean;
  84.       function ReadKey: Char;
  85.       function AltPressed: Boolean;
  86.       function ShiftPressed: Boolean;
  87.       function CtrlPressed: Boolean;
  88.  
  89.   TextMode and PM combined
  90.     To use this version, your program should use the GRAPH unit and
  91.     make sure that the VP/2 BGI Graphics Server, GRAPHSRV.EXE, is
  92.     available somewhere in the PATH.
  93.  
  94.     There are no restrictions of using the Crt unit or other text-based
  95.     units, since the program will be a text-mode application that talks
  96.     to the PM Server Process when graphics are to be displayed.  When
  97.     the InitGraph function is called, the Server Process is
  98.     automatically started and the graphics output window is displayed
  99.     alongside the text mode window of the application.
  100.  
  101.     The Server window is automatically closed when CloseGraph is
  102.     called, or the main program terminates.
  103.  
  104.     When using applications using this interface, it is desirable to
  105.     be able to accept rudimentary keyboard input, no matter if the text
  106.     mode or the PM window currently have focus.  To facilitate this, the
  107.     GRAPH unit implements two functions also declared in the Crt unit;
  108.     these functions collect and return any keypresses detected in either
  109.     window:
  110.  
  111.       function KeyPressed: Boolean;
  112.       function ReadKey: Char;
  113.  
  114.   General considerations
  115.     VP/GRAPH is very compatible with GRAPH from Borland Pascal, but
  116.     is a complex 32-bit multi-threaded framework instead of a simple
  117.     DOS library.
  118.  
  119.     This means that multitasking considerations need to be taken into
  120.     account to make "good" applications.  In DOS, all graph commands are
  121.     reflected on the output display immediately; in OS/2, a separate
  122.     thread "blits" any changed areas to the output window at regular
  123.     intervals.
  124.  
  125.     A few new functions are provided to accomodate multitasking:
  126.  
  127.       var WaitKeypressed: Boolean
  128.         determines whether or not DosSleep() is called if no key is
  129.         ready to be processed when KeyPressed is called.  This should be
  130.         True in tight loops waiting for a keypress, like
  131.           While not keypressed do ;
  132.         and False if the check is used only to check whether a drawing
  133.         loop should be exited.
  134.  
  135.     The following functions are only available in GRAPH.PAS:
  136.  
  137.       var AutoStartServer: Boolean
  138.         determines whether or not the Graph Server should be started
  139.         automatically.  For debugging purposes, it can be handy to
  140.         turn this off and run GRAPHSRV from the command line or even
  141.         to load two copies of VPPM and debug both client and server
  142.         at the same time.
  143.  
  144.       procedure FlushDisplay;
  145.         causes the program to wait until all changes made to the display
  146.         since have been displayed.
  147.  
  148.     The following functions are only available in DGRAPH.PAS:
  149.  
  150.       procedure SuspendRefresh;
  151.         can be called, if you want to draw something complex and do not
  152.         care about it being updated regularly.
  153.  
  154.       procudure EnableRefresh;
  155.         re-enables screen updating.
  156.  
  157.       procedure WaitDraw;
  158.         causes the program to wait until all changes made to the display
  159.         since have been displayed.
  160.  
  161.  
  162. How it works
  163. ------------
  164.   The combined PM/Textmode VP/GRAPH works by having a client text-mode
  165.   application, which sends messages to a PM server process.  The server
  166.   process, GRAPHSRV.EXE, is automatically started when InitGraph is
  167.   called and also terminates automatically when it is no longer needed.
  168.  
  169.   This can be illustrated graphically like this:
  170.  
  171.   Component                                Function
  172.   User application                         User code
  173.    graph.pas                               BGI interface functions
  174.      sends messages to Server Process
  175.  
  176.   Server Process                           Receives and parses messages
  177.     dgraph.pas                             BGI code implementation
  178.       Os2Dive.pas                          DIVE interface for VP/2
  179.  
  180.   For PM applications, the Server layer is not required and the
  181.   layout is
  182.  
  183.   User application                         User code
  184.     dgraph.pas                             BGI code implementation
  185.       Os2Dive.pas                          DIVE interface for VP/2
  186.  
  187.  
  188. Example Code
  189. ------------
  190.   To demonstrate VP/GRAPH, this archive contains two versions of the
  191.   BGIDEMO example from Borland Pascal, changed to Virtual Pascal.  The
  192.   source for the examples is very similar, with only minor differences,
  193.   and both resemble the original Borland source code as well.
  194.  
  195.   The examples are called BGIDEMO.EXE and BGIPM.EXE, respectively.
  196.   BGIDEMO runs as a text mode application and links to the Server, which
  197.   is started automatically.  BGIPM runs as a PM app and does not use
  198.   the server.
  199.  
  200.   When executing the examples, please specify the full path to your
  201.   BP7 BGI fonts, if you have them available.  Without these fonts,
  202.   the demos will fail when trying to display Pie Charts.
  203.  
  204.  
  205. Feedback
  206. --------
  207.   Comments, suggestions and bug reports to this beta are *very* welcome.
  208.   You are encouraged to use and test this software extensively.  When
  209.   we are satisfied that it works well, it will be included in the next
  210.   version of Virtual Pascal for OS/2 and be made freely available to
  211.   all existing customers.
  212.  
  213.   Send feedback to
  214.  
  215.     Mail:      fPrint UK Ltd
  216.                Cambridge House
  217.                100 Cambridge Grove
  218.                Hammersmith
  219.                London W6 0LE
  220.                United Kingdom
  221.                Att: Development
  222.  
  223.     e-mail:    vpascal@ibm.net
  224.     Fax:       +44 181 563 2361
  225.     BBS:       +44 181 563 8624
  226.     www:       http://www.fprint.co.uk/vpascal
  227.  
  228.  
  229. Buying Virtual Pascal for OS/2
  230. ------------------------------
  231.   If you do not yet have a copy of Virtual Pascal for OS/2, get it quick!
  232.   It sells for a recommended retail price of £165, or US$245 and for this
  233.   price you get a thorough printed manual, about 30MB of files on your
  234.   hard disk and the best Pascal development environment for OS/2.
  235.  
  236.   If you live in the US or Canada, contact NITEK Corp. for VP/2 orders:
  237.     Anthony Busigin
  238.     NITEK Corporation
  239.     38 Longview CRT
  240.     London, ON N6K 4J1
  241.     Canada
  242.  
  243.     Tel: (519) 657-4914
  244.     Fax: (519) 657-0283
  245.     E-Mail: busigin@ibm.net
  246.  
  247.   For the nearest local dealer elsewhere in the world, contact fPrint UK
  248.   on one of the above addresses or phone numbers.
  249.  
  250.