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.