Source Code 1992 March

home *** CD-ROM | disk | FTP | other *** search

/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / msdos / turbopas / qwik41a.arc / QWIK41.DOC < prev next >

Wrap

Text File | 1988-05-02 | 22.9 KB | 495 lines

May 02, 1988 QWIK SCREEN UTILITIES Version 4.1A PURPOSE: QWIK screen utilities permit fast screen writing on IBM compatibles on any IBM or Hercules adapter including the new PS/2 systems without "snow" or flicker effects and is compatible with ANY column format (e.g. 40/80 or variable). Written in MASM and implemented in a unit for Turbo Pascal 4.0, these procedures are lightning fast. The code has also been condensed as much as | possible without sacrificing speed - only 1.7k bytes of compiled | code for all 23 procedures! QWIK utilities allow you to write to the screen in absolute coordinates on any video page and are not confined to a Turbo window or to just page 0. TEST DRIVE: | First copy QWIK41A.TPU to QWIK.TPU. Compile and run QWIKDEMO.PAS to get a feel for features and speed. IMPROVEMENTS: | Four new procedures have been added - QwriteMore, QwriteMoreA, | QfillMore, QattrMore. QWIK now keeps track of where the last | character or attribute was written on the screen. Similar to TP's | Write procedure, these Q*More procedures do not need Row and Col | parameters, but simply continue writing where any Q* procedure | left off. This is essential for mid-stream attribute changes. In | addition, Qinit was improved for detection of dual monitors and | Hercules cards. Background color constants have been added for | convenience and speed. The the critical timing for the IBM PC | (8088) with CGA has now been solved. FILES: In this version, QWIK41A.ARC contains: Qwik41a .tpu: Compiled QWIK41 unit of 1300 lines of assembler. Qwik41 .pas: Source code for QWIK41A.TPU. (MASM source code and object files are not included.) Qwik41 .doc: This document. QwikDemo.pas: A demonstration program showing the features and speed of all procedures and is written primarily for color cards, but also works on mono cards. Qinit .doc: Document for Qinit procedure. Qinitest.pas: A program that verifies the equipment detected by the Qinit procedure. Qbench .pas: A timing program that shows "screens/second" for the Q* procedures. Cursor .doc: Document for cursor procedures and functions. TimerD12.inc: Include file to measure elapsed time. License .arc: ARC file containing license agreements PROCEDURES AND FUNCTIONS: In this version, QWIK41A.TPU has the following procedures and functions. To see the parameters needed, see QWIK41.PAS. One initializing procedure: Qinit - Initializing procedure executed by QWIK41A.TPU which sets the global variables for the Q* procedures. It should be executed again after a change from one text mode to another. Three quick direct screen writing procedures, all work with or without attribute change: Qwrite - for any type string or char. QwriteC - for any type string or char; self-centering. QwriteA - for any type variable; specified length and index. (Array-like) Four quick direct screen filling procedures in Rows-by-Cols block parameters: Qfill - repetitive filling with the same character; self-centering, with or without attribute change. QfillC - Same as Qfill, but self-centering. Qattr - repetitive filling with the same attribute only. QattrC - Same as Qattr, but self-centering. Two quick screen storing procedures: QstoreToMem - Saves a Rows-by-Cols block to memory. QstoreToScr - Restores a Rows-by-Cols block to any screen page. Two quick video page changing procedures: QviewPage - Changes the page to be displayed - up to 8! QwritePage - Sets the page on which the Q* procedures are writing. You don't have to write just on the displayed page! Six quick cursor procedures and functions: GotoRC - inverse of Turbo's GotoXY but in absolute coordinates rather than relative to a window. It also works on any video page. ChangeCursor - changes shape and visibility of the cursor; saves old shape, too! CursorOff - Hides cursor. CursorOn - Reveals cursor, again. WhereR - Returns absolute row coordinate for the viewed video page. WhereC - Returns absolute column coordinate for the viewed video page. Four quick appending procedures (like TP "Write") that start writing at QnextOfs in lieu of Row/Col parameters: QwriteMore - like Qwrite. QwriteMoreA - like QwriteA. QfillMore - like Qfill. QattrMore - like Qattr. PROGRAMMING: | It is recommended that you copy QWIK41A.TPU to QWIK.TPU and just | do the following line in your programs: USES Qwik; TP 4.0 Startup - Borland improved the startup of any EXE file. It checks for the video mode to see if it is a valid text mode (0..3,7). If so, it remains in that mode. If not, it is in a graphics mode and it is forced back into the computer's default text mode, whatever that may be. QWIK41 Startup - QWIK41A.TPU automatically runs Qinit the first time. (Turbo's smart compiler does it just once no matter how many times it appears in USES statments throughout your program.) If you change from one text mode to another in a running program, | you still need to run Qinit again. Be sure to read QINIT.DOC for | all of the available video card and system status values. PARAMETERS: Row/Col - The procedures do not check for bounds on the screen, so be sure to stay in range. The procedures were designed for the upper left column on the screen to be 1,1. They also wrap to the next line; they do not truncate at EOL. You of course can have something like Row:=1 and Col:=255 which is equivalent to Row:=3 and Col:=15 on a screen with 80 columns. ColL/ColR - In QwriteC, QfillC, and QattrC, the left and right columns are simply averaged. To center on the full width of an 80 column display, set ColL:=1 and ColR:=80. To center on a certain column number, set both values equal to that column number. Or, to center on any display, set ColL:=1 and ColR:=CRTcols. Rows/Cols - They can be any byte to define the block: Rows-by- Columns starting at Row, Col. Please keep Cols limited to one row. | Attr - Use the convenient attribute constants for the foreground | and background colors supplied in the QWIKxx.PAS file rather than | having to use TP functions or procedures to get a desired color, | for example: | | Qwrite ( 1, 1,White+BlueBG,'My String'); | | will write the text with white on blue attributes. Use of the | constant SameAttr, or negative values, suppress any changes to the | screen attributes and use what's currently on the screen. Of | course, you can still use Turbo's TextColor and TextBackground | procedures, and then use TextAttr as a parameter. Be aware that the 3270 PC ignores the foreground intensity bit, so there are only 8 colors. In addition, 4 colors have different tints: PC Color 3270 PC Color ------------ ------------- Cyan Turquoise Magenta Pink Brown Yellow Light Gray White | ArrayLength - In QwriteA and QwriteMoreA, you can write arrays or partial strings by specifying the ArrayLength and the starting index (aStr[i]). (Qwrite and QwriteC assume the length is the value at aStr[0] and the starting index is aStr[1].) ArrayLength can be any word. For example: MyString:='Step B: Testing out this line.'; QwriteA (1,1,-1,22,MyString[9]); will print out "Testing out this line." Of course, MyString doesn't have to be a string - it can be any type variable or address in memory. aStr - One of the nice improvements of TP 4.0 is that the address of a string is always passed onto to the stack no matter if it's a string value or a variable. So, there is no need to copy strings to the stack and thereby increasing speed. The Qwrite* procedures only use the address. "aStr" is of type "string", now, and not Str80 and there is no need to be concerned about incompatible string types Source/Dest - For Qstores*, this can be a pointer for the heap or an array variable. Be sure there is sufficient room. Storage requirements are: (Rows * Cols shl 1) which is two bytes for every column. For pointers use a format such as: Var MemPtr: ^byte; GetMem (MemPtr,Rows*Cols shl 1); QstoreToMem (Row,Col,Rows,Cols,MemPtr^); Page - The page range depends upon your adapter which is detected | with MaxPage. See QINIT.DOC for the possible ranges. | Q*MORE PROCEDURES | Purpose - Just as the TP Write and WriteLn procedures continue | where the last Write left off, the Q*More procedures, QwriteMore, | QwriteMoreA, QfillMore, and QattrMore, work similarly. | | QnextOfs - Any time a Q* procedure (except QstoreToScr and | QstoreToMem) is used, the global variable QnextOfs is updated. | This value tells the Q*More procedure where to continue writing, | so you don't need Row or Col parameters. This is especially | useful for midstream attribute changes: | | Qwrite ( 1, 1,White+BlueBG ,'There are'); | QwriteMore ( Yellow+BlueBG,' 5 '); | QwriteMore ( White+BlueBG ,'minutes left.'); | | which will write "There are 5 minutes left." as white on blue | except "5" will be yellow on blue. QnextOfs is universal so that | any Q*More procedure can follow any Q* procedure! You can even | modify QnextOfs directly. Just remember that it is 0-based and | that there are two bytes per displayed character. PAGING: If you have a CGA or better, you already have memory on your card for more than the 80x25 display you normally see. The two page procedures allow you to use QWIK utilities on these other pages and display which ever you choose. However, Turbo's procedures such as Write, Window, and GotoXY are dedicated to page 0 only. Be sure to end your programs with "QviewPage (0);". UPGRADING: Here's a list of steps to help you upgrade to QWIK41 from versions prior to QWIK40 on your programs: | 1. Add "Uses Qwik;" 2. Delete the first Qinit. 3. Do a search and replace for the following names. Search Replace with --------- --------------------- CardWait CardSnow Qwait Qsnow QwriteLV QwriteA QwriteCV QwriteC QwriteV Qwrite ActiveDD ActiveDispDev AltDD AltDispDev PCCAltDD AltDispDevPCC Vmode VideoMode 4. Add "CheckSnow:=Qsnow" early in the program and after each Qinit if you use the CRT unit. 5. See REVISIONS for changes of type. TIPS: CheckSnow - If you plan on using the standard CRT unit, place the following line early in your programs and after each Qinit. CheckSnow:=Qsnow; Qinit appears to be more extensive in it's testing for wait-for- | retrace. Then, Write and WriteLn will work faster if DirectVideo is true. Multi-Tasking - Currently, QWIK does not attempt to modify Page0seg for multi-tasking software, but the variables have been set up so you can do this. Take DESQview for example; rather than writing direct to screen memory, DESQview allocates a presentation buffer in RAM. All direct screen write procedures can treat the presentation buffer just like the video buffer, except that Qsnow can always be false. Then, DESQview copies the correct portions to the video buffer. Here's an example procedure that would modify Page0seg: uses DOS; procedure GetVideoBuffer (VAR Page0seg: word); begin Regs.es:=Page0seg; Regs.di:=0; Regs.ah:=$FE; Intr ($10,Regs); Page0seg:=Regs.es; end; This procedure also works for 3270 PC. If neither DESQview nor the 3270 PC are present, then Page0seg will still have the same value. To update the display on the 3270 PC when using multi-tasking, use the following procedure: uses DOS; procedure UpdateVideoDisplay (Row, Col: byte; NumOfChars: word); begin Regs.es:=Page0seg; Regs.di:=pred(Row)*CRTcols + pred(Col); Regs.cx:=NumOfChars; Intr ($10,Regs); Qseg:=Page0seg; end; where Row and Col is the position in the presentation buffer to be updated and only for NumOfChars. CardSeg will still have the original segment of the video card. EgaMono - You should be aware that another constant also named EGAMono is used by the DetectGraph procedure in the Graph unit, but fortunately, they have the same value! Longer names - If you wish to be more explicit with procedure, function, and variable names, you can always add the unit name as a prefix: Qwik.GotoRC (1,1); MyCols:=Qwik.CRTcols; Q* Convention - The "Q" in front of a procedure means that it | depends on the data initialized by Qinit. Others do not. In | addition, they keep track of the last character or attribute | written to the screen by updating QnextOfs (except Qstores* which | leaves it unaltered). SPEED: How fast is fast? Well, I thought it would be good idea to have some criteria to get a feeling for speed. The units I decided to use for comparison are "screens/second". To make one screen, a procedure is repeated with a FOR loop to fill several 80x25 pages and timed. Qwrite- use 80 character strings, and Qattr and Qfill use Rows:=25 and Cols:=80. Here are some samples from the systems that have been tested. My own computer is the AT&T 6300+ which uses Intel 80286. Monochrome (MDA) speeds are close to EGA speeds. ------------------ S C R E E N S / S E C O N D ------------------ Chng XT(4.77 MHz) M30 M50 PCC ATT 6300+ Procedure Attr EGA CGA MCGA VGA LCD EGA CGA --------- ---- ------------ ----- ----- ----- ----------- Qwrite Yes 32.8 9.5 75.4 88.4 40.0 112.1 16.7 No 42.4 9.5 90.0 138.1 48.6 119.5 16.8 QwriteC Yes 32.6 9.5 74.9 89.0 39.5 111.0 16.8 No 41.6 9.5 89.3 138.1 47.8 119.0 16.8 QwriteA Yes 32.6 9.5 74.9 88.4 39.7 111.3 16.8 No 42.0 9.5 89.3 138.1 47.8 119.5 16.8 QfillC Yes 81.2 11.9 166.6 147.3 122.5 244.3 21.5 No 72.6 7.4 141.3 174.4 90.5 176.9 14.0 Qfill Yes 81.2 11.8 164.1 147.3 122.5 246.1 21.5 No 73.7 7.4 141.3 174.4 90.5 177.9 14.0 Qattr Yes 72.6 7.4 141.3 174.4 90.5 177.9 14.0 QattrC Yes 72.6 7.4 141.3 174.4 90.5 177.9 14.0 QstoreToMem n/a 59.1 7.2 111.6 127.4 78.4 181.9 13.8 QstoreToScr n/a 59.1 7.0 111.6 126.2 78.4 183.9 13.7 | For those interested in comparisons, QWIK is much faster than the | TP4 direct video routines and FastWrite by the following | percentage: | | Procedure CGA cards All Other cards | --------- --------- --------------- | Writeln 125% 650% | FastWrite 25% 14% | CRITICAL TIMING: | | The timing on the IBM PC (Intel 8088 at 4.77MHz) with a CGA is | critical for storing characters and attributes as words because of | the CPU architecture and slow speed. Although previous versions | kept the timing as tight as possible, there still remained a hint | of snow in column 1. This problem has now been solved with a | minor code change. So the routines still run at the same speed, | but there is absolutely no snow! I am not aware of any other | routines that have done this correctly. CODE SIZE: If you use a QWIK procedure, the entire object file containing that procedure will be linked into your program no matter if its other procedures are used or not. Fortunately, QWIK is quite small at a total of 1696 bytes. Here's linked code size: FILE NAME BYTES PROCEDURES ------------ ----- ---------------------------------------------- Qinit .obj 496 Qinit - always linked when QWIK is USEd Qwrites .obj 341 Qwrite,QwriteC,QwriteA,QwriteMore,QwriteMoreA Qfills .obj 430 Qfill,Qattr,QfillC,QattrC,QfillMore,QattrMore Qstores .obj 202 QstoreToScr,QstoreToMem Qpages .obj 56 QwritePage,QviewPage Cursor .obj 105 GotoRC,CursorChange,CursorOff/On,WhereR/C CpuIdent.obj 42 GetCpuID Qwik .tpu 24 Initialize and paragraph round up APPLICATIONS: Multi-level Windows - An application of QWIK41A.TPU is multi-level windows. The code is available in a file called WNDW40.ARC. It creates protected windows with serial or random access that can be moved or removed and has Macintosh-like special special effects. Multi-level Pull-down Menus - An application of windows is multi- level pull-down menus. I have already created some very thorough code in a file called PULL20.ARC. It is fully featured and fully configurable. Includes execute, single, and multiple choice menus, unlimited nested submenus, data entry windows, help windows, directory windows, message system, and fully completed interfaces. On-line source - All updated files and later versions can be found on the CompuServe Borland Forum (GO BPROGA) in the MSDOS TP 4.0 Data Library or the IBM software forum (GO IBMSW) data library. CREDITS: Without the assistance and original ideas from Brian Foley [CIS 76317,3247], these routines would not have been written. Copyright (c) 1986-1988 by James H. LeMay If there are any problems, please let me know. Jim LeMay [CIS 76011,217] (1-817-735-4833 after 1800 CST) 6341 Klamath Rd., Ft. Worth, TX, 76116. PRICE: After much thought, I have decided to make these procedures into ShareWare. The cost may range from $8 to $18 depending on your application. I do enjoy assisting others in their programming, but lack of reimbursement is expensive for me! Please help out. See the license statement, STATMENT.LIC, in LICENSE.ARC for details. If the response will let me break even, I will continue support. REVISIONS: Version 4.0 (12-01-87): Converted QWIK30 to QWIK40 to work on Turbo Pascal 4.0. Deleted QwriteV and QwriteCV. Added WhereR and WhereC. Added Hercules and IBM 3270 PC detection. Renamed the following variables: From To ---------- ------------ CardWait CardSnow Qwait Qsnow QwriteLV QwriteA QwriteCV QwriteC QwriteV Qwrite ActiveDD ActiveDispDev AltDD AltDispDev PCCAltDD AltDispDevPCC Vmode VideoMode Added the following variables: VideoPage, CRTcols, CRTrows, CardSeg, Have3270, ActiveDispDev3270 Added the following constants: NoHerc, HgcMono, HgcPlus, HercInColor Types were changed on the following items: - Strings passed to Qwrite* are of type String rather than Str80. (Should not be of any consequence.) - The CursorChange parameters are now word. - EgaFontSize, CRTcolumns, CardSeg, Page0seg, Qseg, AltDispDevPCC and ArrayLength are now word. Version 4.1a (05-01-88): Added QwriteMore, QwriteMoreA, QfillMore, and QattrMore procedures. Added QnextOfs for the Q*More procedures. Improved video detection in Qinit for dual monitors, Hercules cards, and system hardware detection. Included background color constants to use instead of an attribute function. Reduced code size about 10%. Solved critical timing problem on IBM PC with CGA - at last! QWIK now uses the global variable CRTcols and not the absolute variable CRTcolumns for offset calculations.