home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / vpbgib2.zip / README.TXT < prev   
Text File  |  1996-11-02  |  19KB  |  451 lines
  1.   London, November 1996
  2.   ** BETA Release 2 **
  3.   BGI Graphics for Virtual Pascal for OS/2 v1.1
  4.  
  5.  
  6. This archive contains the second 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.  BEFORE RUNNING, PLEASE REFER
  12. TO THE OUTSTANDING PROBLEMS SECTION!
  13.  
  14.  
  15. This document
  16. -------------
  17. The following topics are covered by this document:
  18.  
  19.   What is is and How it works
  20.   Problems from Beta 1 that are resolved and new features
  21.   Outstanding items and known problems
  22.   Using the library
  23.   Debugging the library
  24.   Optimising GRAPH/VP
  25.   BETA messages
  26.   The innards
  27.   Example Code
  28.   Feedback
  29.   Buying Virtual Pascal for OS/2
  30.  
  31.  
  32. What it is and How it works
  33. ---------------------------
  34. The GRAPH unit in Borland Pascal is used to produce full-screen
  35. graphics. In OS/2, full screen graphics are not desirable and a better
  36. solution is available: DIVE. Using this technology, which is available
  37. from OS/2 Warp and later, it is possible to open a window and get direct
  38. access to video memory under OS/2.  (NOTE: Preliminary tests show that
  39. DIVE without Warp FixPack 17 applied has serious flaws.  Please refer to
  40. the notes below for details on this problem).
  41.  
  42. The graph unit in DOS is used in simple text-mode applications that can
  43. be switched to graphics mode to display graphics.  In VP/2, GRAPH can be
  44. used to make standalone graphical PM applications, or to produce apps that
  45. combine PM and text mode using sophisticated multi-threaded background
  46. processing.
  47.  
  48. This beta represents the initial effort to make programs written for the
  49. GRAPH unit in DOS recompile with very few changes and run in OS/2. A few
  50. functions are not implemented, and some functions may work slightly
  51. differently than in Borland Pascal.
  52.  
  53.  
  54. Problems from Beta 1 that are resolved and new features
  55. -------------------------------------------------------
  56.  - All drawings are now much faster.  The PM version is now quite
  57.    fast, and the Txt version is adequately fast.
  58.  
  59.  - Floodfill has been implemented
  60.  
  61.  - Sector and Pieslice are now filled if specified
  62.  
  63.  - GetImage and PutImage are implemented for Client/Server version
  64.  
  65.  - The appearance of all drawings with ThickWidth, particularly round
  66.    objects, are much improved
  67.  
  68.  - All reasonable resolutions supported.  Use VPInitGraph to start a window
  69.    of any resolution using VPInitGraph( xRes, yRes, BGIFontPath )
  70.  
  71.  - Mouse support.  Similar to KeyPressed and Readkey, functions for
  72.    querying mouse position and events are available.
  73.  
  74.  - More variables for controlling Client/Server interaction.
  75.  
  76.  - BGI font output is much faster than before
  77.  
  78.  - The 3D bars of the BGIDEMO example are now filled
  79.  
  80.  - An error message will be displayed if DIVE is not installed
  81.  
  82.  - If an old version of DIVE is used, accelerated blitting is disabled.
  83.  
  84.  - If no warning messages should be displayed, set Os2Dive.SuppressMessages
  85.    to True.
  86.  
  87.  - Beta messages are displayed on screen when initialising.
  88.  
  89.  - This readme file has been updated
  90.  
  91.  
  92. Outstanding items and known problems
  93. ------------------------------------
  94.  - Font style/size and direction not implemented for the 8x8 default font
  95.  
  96.  - Graphics output is somewhat slower than in DOS.
  97.  
  98.  - Changing the palette on the fly is very slow
  99.  
  100.  - IMPORTANT: The shipping version of VP/2 v1.1 has an error in the
  101.    SysUtils unit. When an exception occurs, the error handler in
  102.    SysUtils itself causes an exception.
  103.    To prevent this from happening, do the following:
  104.      - Edit SYSUTILS.RC in the SOURCE\RTL directory.
  105.        Change the SException string (line 35) by removing the last %s,
  106.        making it read
  107.          SException, "Exception %s in module %s at %p.\x0A%s%s"
  108.      - Recompile SYSUTILS.RC by typing
  109.          RC -r SYSUTILS.RC
  110.  
  111.  
  112. Using the library
  113. -----------------
  114. The library includes all standard functions of BP7's GRAPH unit and
  115. many programs written using GRAPH will work with this version with
  116. few or no changes.  The only change that must always be made is to
  117. include USE32 in the Uses clause of the program.
  118.  
  119. Before beginning work with the library, UNZIP all files in this archive
  120. to a directory on your hard disk.
  121.  
  122.   Two flavours
  123.   ------------
  124.   GRAPH/VP comes in two flavours.  One is for programs that mix textmode
  125.   output with graphics (Typically a program that displays a graph or an
  126.   illustration inbetween) and the other is for programs that are pure
  127.   graphics (Games, for example).
  128.  
  129.   PM Version
  130.     To use the PM only version, your program should add DGRAPH to the
  131.     uses clause inctead of Graph.  The Linker Target should be set to
  132.     PM, either in the Linker dialog or by entering a {$PMTYPE:PM}
  133.     compiler directive in the code of the main program.
  134.  
  135.     Since the program is not a text-mode application, it must not use
  136.     the Crt unit and no longer has access to the KeyPressed, Readkey,
  137.     etc functions of that unit.  Instead, DGRAPH implements a small set
  138.     of replacement functions that can be called instead:
  139.  
  140.       procedure Delay(MS: Longint);
  141.       function KeyPressed: Boolean;
  142.       function ReadKey: Char;
  143.       function AltPressed: Boolean;
  144.       function ShiftPressed: Boolean;
  145.       function CtrlPressed: Boolean;
  146.  
  147.   Mouse Support
  148.     In both versions, mouse position and events can be queried using
  149.     the following functions:
  150.  
  151.       procedure GetMousePos( var x,y: Word );
  152.         Returns the current position of the mouse
  153.  
  154.       function  MouseClicked: Boolean;
  155.         Similar to keypressed; returns True, if a mouse event is waiting
  156.  
  157.       procedure GetMouseEvent( var M: MouseEventRecT );
  158.         Similar to Readkey; waits for a mouse event and returns it.
  159.  
  160.       function  ReadKeyOrMouse( TimeOut: Word; var Mouse: Boolean;
  161.         var Key: Char; var MEvent: MouseEventT; var mx, my: Word ): Boolean;
  162.         Combined Readkey and GetMouseEvent function with timeout.  Waits
  163.         for up to TimeOut milli-seconds (-1 means indefinite wait) and
  164.         returns the next keyboard- or mouse-event.  If a mouse event
  165.         is returned, Mouse is set to True, otherwise to False.  Mx an My
  166.         is the position of the mouse at the time of the event.
  167.  
  168.   TextMode and PM combined
  169.     To use this version, your program should use the GRAPH unit and
  170.     make sure that the VP/2 BGI Graphics Server, GRAPHSRV.EXE, is
  171.     available somewhere in the PATH.
  172.  
  173.     There are no restrictions of using the Crt unit or other text-based
  174.     units, since the program will be a text-mode application that talks
  175.     to the PM Server Process when graphics are to be displayed.  When
  176.     the InitGraph function is called, the Server Process is
  177.     automatically started and the graphics output window is displayed
  178.     alongside the text mode window of the application.
  179.  
  180.     The Server window is automatically closed when CloseGraph is
  181.     called, or the main program terminates.
  182.  
  183.     When using applications using this interface, it is desirable to
  184.     be able to accept rudimentary keyboard input, no matter if the text
  185.     mode or the PM window currently have focus.  To facilitate this, the
  186.     GRAPH unit implements two functions also declared in the Crt unit;
  187.     these functions collect and return any keypresses detected in either
  188.     window:
  189.  
  190.       function KeyPressed: Boolean;
  191.       function ReadKey: Char;
  192.  
  193.   General considerations
  194.     VP/GRAPH is very compatible with GRAPH from Borland Pascal, but
  195.     is a complex 32-bit multi-threaded framework instead of a simple
  196.     DOS library.
  197.  
  198.     This means that multitasking considerations need to be taken into
  199.     account to make "good" applications.  In DOS, all graph commands are
  200.     reflected on the output display immediately; in OS/2, a separate
  201.     thread "blits" any changed areas to the output window at regular
  202.     intervals.
  203.  
  204.     A few new functions are provided to accomodate multitasking:
  205.  
  206.       var WaitKeypressed: Boolean
  207.         determines whether or not DosSleep() is called if no key is
  208.         ready to be processed when KeyPressed is called.  This should be
  209.         True in tight loops waiting for a keypress, like
  210.           While not keypressed do ;
  211.         and False if the check is used only to check whether a drawing
  212.         loop should be exited.
  213.  
  214.     The following functions are only available in GRAPH.PAS:
  215.  
  216.       var AutoStartServer: Boolean
  217.         determines whether or not the Graph Server should be started
  218.         automatically.  For debugging purposes, it can be handy to
  219.         turn this off and run GRAPHSRV from the command line or even
  220.         to load two copies of VPPM and debug both client and server
  221.         at the same time.
  222.  
  223.       procedure FlushDisplay;
  224.         causes the program to wait until all changes made to the display
  225.         since have been displayed.
  226.  
  227.       var ImmediateUpdate: Boolean
  228.         When true, all commands are immediately sent to the server for
  229.         processing; this is good for animated graphics or for debugging.
  230.         When false, commands are queued and sent to the server in chunks.
  231.         This gives faster processing but more "chunky" screen output.
  232.  
  233.       var MinFrameRate: Longint
  234.         Default is 5 frames per second; this value is irrelevant if
  235.         ImmediateUpdate is true.  Otherwise, setting this value ensures
  236.         that the Server gets all waiting commands at least MinFrameRate
  237.         times per second.
  238.  
  239.  
  240.     The following functions are only available in DGRAPH.PAS:
  241.  
  242.       procedure SuspendRefresh;
  243.         can be called, if you want to draw something complex and do not
  244.         care about it being updated regularly.
  245.  
  246.       procudure EnableRefresh;
  247.         re-enables screen updating.
  248.  
  249.       procedure WaitDraw;
  250.         causes the program to wait until all changes made to the display
  251.         since have been displayed.
  252.  
  253.  
  254. Debugging the library
  255. ---------------------
  256.   When debugging programs using GRAPH, a few of the more advanced
  257.   debugging features of VP/2 are handy.
  258.  
  259.   If you are writing a program for use with the client/server version,
  260.   and experience traps and exceptions in the GRAPHSRV executable, you
  261.   can do the following:
  262.  
  263.     - Insert
  264.         Graph.AutoStartServer := False;
  265.         Graph.WaitKeyPressed := True;
  266.       into your code before calling InitGraph.
  267.  
  268.     - Start a new copy of the VP/PM IDE.  To make OS/2 start a new copy
  269.       when clicking on the icon (instead of activating the already
  270.       active copy), open the properties/settings notebook for VP/PM,
  271.       go to the Window tab, and change "Object open behavior" to "Create
  272.       new window".
  273.  
  274.     - In the second instance of VP/PM, load GRAPHSRV.PAS and execute it
  275.       without any parameters.  This starts the Graph server process.
  276.  
  277.     - Switch back to the first copy of VP/PM and compile and run your
  278.       program.
  279.  
  280.   You now have full control over both running processes.  If an exception
  281.   occurs in either process, the relevant copy of VP/PM allows you to
  282.   inspect variables, determine the cause of the exception, etc.
  283.  
  284.   A few options you may want to enable, depending on your specific
  285.   problem:
  286.     Options|Debugger menu:
  287.       Hard PM mode - should always be on!  Without this option enabled,
  288.       debugging Graph is likely to cause OS/2 to hang or crash.
  289.  
  290.       Break on exception - should probably be on.  When this option
  291.       is enabled, the program being debugged does not terminate when
  292.       an exception is raised, but instead halts execution at the
  293.       offending instruction and allows you to inspect variables,
  294.       parameters, call stack, etc.
  295.  
  296.     View|Exceptions dialog:
  297.       Check XCPT_ACCESS_VIOLATION and other exceptions you experience.
  298.       When an exception of this type is raised, the debugger immediately
  299.       stops execution and opens the CPU window at the location of the
  300.       error.
  301.  
  302.   Lastly, a very helpful feature is the Data Point.  To monitor the
  303.   flow of the program, for example the position of the mouse or the
  304.   stream of commands sent back and forth between the client and server,
  305.   set a breakpoint at the location of interest (Ctrl-F8).  Then open
  306.   the View|Breakpoints dialog and position the cursor on the new
  307.   breakpoint.  Press Alt-F10 to see the local menu for the Breakpoints
  308.   window and select "Change options...".
  309.   In this dialog, you can change the breakpoint to be a Log Point by
  310.   removing the check next to "Break" and set a check next to "Log".
  311.   Enter the expressions you wish to log in the "Log expression"
  312.   entry field, separated by semicolons, for example
  313.     X;Y;MouseStatus
  314.   Now, before starting execution, open the Log window (View|Log).  Every
  315.   time your data/log point is reached, a line displaying the values
  316.   of the Log expression is added to the Log window.
  317.  
  318.  
  319. Optimising GRAPH/VP
  320. -------------------
  321.   DIVE is not the fastest engine for outputting graphics and cannot
  322.   compete with full screen DOS graphics in terms of speed.  Output to
  323.   DIVE is performed in multiple steps, where the program first requests
  324.   access to the video buffer, then writes to it, and then tells DIVE to
  325.   reflect the changes on the display.
  326.  
  327.   When drawing many small items on the screen, GRAPH/VP implements an
  328.   optimising technique whereby only changed areas are updated, instead
  329.   of always updating the entire screen.  For demo programs such as
  330.   BGIDEMO, this accelerates the frame rate by as much as a factor of
  331.   10, but does not come without a price.
  332.  
  333.   Early versions of DIVE (Warp without fixpacks applied) cause OS/2 to
  334.   hang when this method is used.  Copying the DIVE.DLL from FixPak 17 or
  335.   applying the fixpak solves the problem however, and GRAPH attempts to
  336.   determine the current version installed during initialization.  If
  337.   an old version is found (It simply checks the file date), the
  338.   Os2Dive.FastBlitSupported variable is set to False and the entire
  339.   screen is updated every time a change is made.
  340.  
  341.   In some cases, it is desirable to have this behaviour, even if the
  342.   installed version of DIVE does support the optimised output - it
  343.   depends on the application.  In this case, call the SlowBlit
  344.   procedure of the Graph unit after calling InitGraph or VPInitGraph
  345.   to disable accelerated output.
  346.  
  347.  
  348. BETA messages
  349. -------------
  350.   When starting a program using Graph/VP, a messagebox is displayed
  351.   on screen, either notifying of an old DIVE version or telling users
  352.   that a beta version of GRAPH/VP has been used.
  353.  
  354.   To prevent these messages from being displayed, set the
  355.   Os2Dive.SuppressMessages variable to True.  Error messages are
  356.   still displayed if DIVE is not installed or cannot be initialised.
  357.  
  358.  
  359. The innards
  360. -----------
  361.   The combined PM/Textmode VP/GRAPH works by having a client text-mode
  362.   application, which sends messages to a PM server process.  The server
  363.   process, GRAPHSRV.EXE, is automatically started when InitGraph is
  364.   called and also terminates automatically when it is no longer needed.
  365.  
  366.   This can be illustrated graphically like this:
  367.  
  368.   Component                                Function
  369.   User application                         User code
  370.    graph.pas                               BGI interface functions
  371.      sends messages to Server Process
  372.  
  373.   Server Process                           Receives and parses messages
  374.     dgraph.pas                             BGI code implementation
  375.       Os2Dive.pas                          DIVE interface for VP/2
  376.  
  377.   For PM applications, the Server layer is not required and the
  378.   layout is
  379.  
  380.   User application                         User code
  381.     dgraph.pas                             BGI code implementation
  382.       Os2Dive.pas                          DIVE interface for VP/2
  383.  
  384.  
  385. Example Code
  386. ------------
  387.   To demonstrate VP/GRAPH, this archive contains two versions of the
  388.   BGIDEMO example from Borland Pascal, changed to Virtual Pascal.  The
  389.   source for the examples is very similar, with only minor differences,
  390.   and both resemble the original Borland source code as well.
  391.  
  392.   The examples are called BGIDEMO.EXE and BGIPM.EXE, respectively.
  393.   BGIDEMO runs as a text mode application and links to the Server, which
  394.   is started automatically.  BGIPM runs as a PM app and does not use
  395.   the server.
  396.  
  397.   When executing the examples, please specify the full path to your
  398.   BP7 BGI fonts, if you have them available.  Without these fonts,
  399.   the demos will fail when trying to display Pie Charts.
  400.  
  401.  
  402.   The second example is a very simple drawing program, supplied as
  403.   DRAW.EXE and DRAWPM.EXE.  This program illustrates how to use the
  404.   mouse and keyboard support functions.
  405.  
  406. Feedback
  407. --------
  408.   Comments, suggestions and bug reports to this beta are *very* welcome.
  409.   You are encouraged to use and test this software extensively.  When
  410.   we are satisfied that it works well, it will be included in the next
  411.   version of Virtual Pascal for OS/2 and be made freely available to
  412.   all existing customers.
  413.  
  414.   Send feedback to
  415.  
  416.     Mail:      fPrint UK Ltd
  417.                Cambridge House
  418.                100 Cambridge Grove
  419.                Hammersmith
  420.                London W6 0LE
  421.                United Kingdom
  422.                Att: Development
  423.  
  424.     e-mail:    vpascal@ibm.net
  425.     Fax:       +44 181 563 2361
  426.     BBS:       +44 181 563 8624
  427.     www:       http://www.fprint.co.uk/vpascal
  428.  
  429.  
  430. Buying Virtual Pascal for OS/2
  431. ------------------------------
  432.   If you do not yet have a copy of Virtual Pascal for OS/2, get it quick!
  433.   It sells for a recommended retail price of £165, or US$245 and for this
  434.   price you get a thorough printed manual, about 30MB of files on your
  435.   hard disk and the best Pascal development environment for OS/2.
  436.  
  437.   If you live in the US or Canada, contact NITEK Corp. for VP/2 orders:
  438.     Anthony Busigin
  439.     NITEK Corporation
  440.     38 Longview CRT
  441.     London, ON N6K 4J1
  442.     Canada
  443.  
  444.     Tel: (519) 657-4914
  445.     Fax: (519) 657-0283
  446.     E-Mail: busigin@ibm.net
  447.  
  448.   For the nearest local dealer elsewhere in the world, contact fPrint UK
  449.   on one of the above addresses or phone numbers.
  450.  
  451.