home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / QWIK21.ZIP / QWIK21.DOC < prev    next >
Encoding:
Text File  |  1986-12-09  |  16.7 KB  |  365 lines
  1.                                                         December 09, 1986
  2.  
  3.                                Q SCREEN UTILITIES
  4.                                    Version 2.1
  5.  
  6.         PURPOSE:
  7.  
  8.         Q screen utilities permit fast screen writes on IBM compatibles
  9.         with MDA, CGA, and/or EGA adapters without "snow" or flicker
  10.         effects and is compatible with ANY column format (e.g. 40/80 or
  11.         variable).  Written in Turbo Pascal inline assembler, these
  12.         procedures are lightning fast.  The code has also been condensed
  13.         as much as possible without sacrificing speed - only 1.4k bytes
  14.         of compiled code for all 17 procedures!
  15.  
  16.  
  17.         TEST DRIVE:
  18.  
  19.         Compile and run QDEMO.PAS to get a feel for features and speed.
  20.  
  21.  
  22.         IMPROVEMENTS:
  23.  
  24.         In this version, I have tried to compile the efforts of Bela
  25.         Lubkin and Brian Foley with some concepts of my own for making
  26.         these procedures fast, easy to use, and compatible with current
  27.         and future products.  The inline code has been revised to allow
  28.         column formats of ANY size (e.g. 40,80, or variable) and allow
  29.         global access to addresses and wait-for-retrace.  This gives you
  30.         the power to have multiple pages (4 on CGA and 8 on EGA) in memory
  31.         that you already have.  The filling and transfer procedures now
  32.         work in block mode rather than line mode which is faster and much
  33.         simpler with the use of Rows-by-Columns parameters.
  34.  
  35.  
  36.         UTILITIES:
  37.  
  38.         In this version, QWIK21.ARC contains:
  39.  
  40.            Qinit  .inc:  Initializing procedure required to be compiled
  41.                          before all Q utilities.  Also has a function to
  42.                          check for EGA cards.
  43.            Qwrites.inc:  Five Quick direct screen writing procedures:
  44.                          QwriteLV - referenced (VAR) strings, specified
  45.                                     length and index.
  46.                          QwriteV  - referenced (VAR) strings
  47.                          Qwrite   - value strings
  48.                          QwriteC  - value strings, self-centering
  49.                          QwriteCV - referenced (VAR) strings, self-
  50.                                     centering
  51.            Qfills .inc:  Four Quick direct screen filling procedures
  52.                          in Rows-by-Cols block parameters:
  53.                          QfillC   - repetitive filling with the same
  54.                                     character and self-centering
  55.                          Qfill    - repetitive filling with the same
  56.                                     character
  57.                          Qattr    - repetitive filling with the same
  58.                                     attribute only
  59.                          QattrC   - repetitive filling with the same
  60.                                     attribute and self-centering
  61.            Qstores.inc:  Two Quick storing procedures:
  62.                          QstoreToMem - Saves a Rows-by-Cols block
  63.                                        to memory.
  64.                          QstoreToScr - Restores a Rows-by-Cols block
  65.                                        to any screen page.
  66.            Qpage  .inc:  Two Quick direct screen changing procedures:
  67.                          QviewPage  - Changes the page to be
  68.                                       displayed - up to 8!
  69.                          QwritePage - Sets the page on which the
  70.                                       Q utilities are writing.  You
  71.                                       don't have to write just on
  72.                                       the displayed page!
  73.            Cursor .inc:  Two Quick cursor procedures:
  74.                          GotoRC       - inverse of Turbo's GotoXY
  75.                          ChangeCursor - changes shape and visibility
  76.                                         of the cursor; saves old, too!
  77.            Qwik21 .inc:  Has all of the above routines but compiles much
  78.                          faster because there are few comments.
  79.            Qwik21 .doc:  This document.
  80.            Qdemo  .pas:  A demonstration program showing the features and
  81.                          speed of all procedures and is written for all
  82.                          cards and column modes.  It also has some appli-
  83.                          cation procedures like Qbox for making windows.
  84.            Qbench .pas:  A timing program that shows "screens/second" for
  85.                          the Q utilities.
  86.  
  87.         Qwrites.inc and Qfills.inc work with or without attributes changes.
  88.         (Do not run QwritesDisp and QfillsDisp alone as they are just dummy
  89.         names for compiling.)
  90.  
  91.  
  92.         PROGRAMMING:
  93.  
  94.         To use the procedures, just simply pick out the ones you need and
  95.         include them in your programs.  QINIT.INC must be included first.
  96.         Be sure to read the MODIFICATIONS section below before editing
  97.         the modules.  Only one initializing statement is necessary before
  98.         Q utilities are used (not required for cursor.inc):
  99.  
  100.             Qinit;
  101.  
  102.         This procedure automatically configures the procedures to your
  103.         machine and also makes it portable to others.
  104.  
  105.  
  106.         MODULES:
  107.  
  108.         The coding has been reduced by making the display loops into a
  109.         subroutine and programming the procedures to access it.  These
  110.         were combined to make modules - two in this package.  It is
  111.         important that the procedures within the module remain in their
  112.         present order because the CALL addresses were compiled in
  113.         assembler and not with Turbo.  But you can easily delete the
  114.         procedures you don't need.  Refer to MODIFICATIONS below.
  115.  
  116.  
  117.         PARAMETERS:
  118.  
  119.         Row/Col - The procedures do not check for bounds on the screen,
  120.         so be sure to stay in range.  The procedures were designed for
  121.         the upper left column on the screen to be 1,1.  If you want 0,0,
  122.         refer to MODIFICATIONS below.  They also wrap to the next line;
  123.         they do not truncate at EOL.  You of course can have something
  124.         like Row:=1 and Col:=255 which is equivalent to Row:=3 and
  125.         Col:=15 on a screen with 80 columns.
  126.  
  127.         ColL/ColR - In QwriteC, QwriteCV, QfillC, and QattrC, the left
  128.         and right columns are simply averaged.  To center on the full
  129.         width of an 80 column display, set ColL:=1 and ColR:=80.  To
  130.         center on a certain column number, set both values equal to that
  131.         column number.
  132.  
  133.         Rows/Cols - They can be any positive integer to define the block
  134.         - Rows-by-Columns starting at Row, Col.  Values <=0 will simply
  135.         abort the procedure.  Please keep Cols limited to one row.
  136.  
  137.         Attr - The attributes range from 0 to 255.  Values greater than
  138.         255 will be operated by modulo 256 to stay useful.  Negative
  139.         values suppress any changes to the screen attributes and use
  140.         what's currently on the screen.  For help with attribute values,
  141.         use Brian Foley's FWATTR.INC on Borland's Programming Forum on
  142.         CompuServe in Turbo Pascal Data Library for MSDOS.  You can also
  143.         use Turbo's TextColor and TextBackground procedures, and then
  144.         use an absolute variable assigned at Dseg:8 (see Qdemo.pas for
  145.         an example).
  146.  
  147.         Length - In QwriteLV, you can write partial strings by specifying
  148.         the Length and starting index (St[i]).  All other Qwrite procedures
  149.         assume length is the value at St[0] and the starting index is St[1].
  150.         Length can be any positive integer.
  151.  
  152.         St - The original type was set for string length of 80 characters
  153.         which my be changed to any value between 1 and 255.  Be sure to
  154.         change all type statements to reflect it though!
  155.  
  156.         Source/Dest - For Qstores.inc, this can be a pointer for the heap
  157.         or an array variable.  Be sure there is sufficient room.  Storage
  158.         requirements are: (Rows * Cols shl 1) which is two bytes for
  159.         every column.  For pointers use a format such as:
  160.  
  161.             Type BytePtr = ^byte;
  162.             Var  MemPtr: BytePtr;
  163.             GetMem (MemPtr,Rows*Cols shl 1);
  164.             QstoreToMem (Row,Col,Rows,Cols,MemPtr^);
  165.  
  166.         Page - The page range depends upon your adapter as follows:
  167.                MDA - On Monochrome cards, there is only page 0.
  168.                CGA - Page 0 to 3 in modes 2 and 3 (80 column),
  169.                      page 0 to 7 in modes 0 and 1 (40 column).
  170.                EGA - Page 0 to 7 in any mode (as I understand it).
  171.  
  172.         Order - You may rearrange the parameters in any order you prefer.
  173.         The arrangement was made to facilitate readability and keeping
  174.         the coordinates on the left side of the display.
  175.  
  176.  
  177.         PAGING:
  178.  
  179.         If you have a CGA or better, you already have memory on your card
  180.         for more than the 80x25 display you normally see.  The two page
  181.         procedures allow you to use Q screen utilities on these other pages
  182.         and display which ever you choose.  However, Turbo's procedures
  183.         such as Write, Window, and GotoXY are dedicated to page 0 only.
  184.         I have included GotoRC as one utility that works on all pages.  If
  185.         you want more procedures for this, refer to Neil Rubenking's
  186.         VIDPAG.PAS on Borland's Programming Forum.  Be sure to end your
  187.         programs with "QviewPage (0);".
  188.  
  189.  
  190.         SPEED:
  191.  
  192.         How fast is fast?  Well, I thought it would be good idea to have
  193.         some criteria to get a feeling for speed.  The units I decided
  194.         to use for comparison are "screens/second".  To make one screen,
  195.         a utility is repeated with a FOR loop to fill several 80x25
  196.         pages and timed.  QwriteXX use 80 character strings, and Qattr
  197.         and Qfill use Rows:=25 and Cols:=80.  At the moment, all I have
  198.         are ratings on my own computer (AT&T 6300+) which uses Intel
  199.         80286.  Other processors will be proportional.  Monochrome (MDA)
  200.         speeds are identical to EGA speeds.
  201.  
  202.         ------------------ S C R E E N S / S E C O N D ------------------
  203.                     Chng -- 80286 --    -- 8086 ---    -- 8088 ---
  204.         Procedure   Attr EGA     CGA    EGA     CGA    EGA     CGA
  205.         ---------   ---- -----------    -----------    ------------
  206.         QwriteLV    Yes  111.3  16.8
  207.                     No   119.5  16.8
  208.         QwriteV     Yes  112.1  16.7
  209.                     No   119.5  16.8
  210.         Qwrite      Yes   87.3  14.4
  211.                     No    92.0  14.4
  212.         QwriteC     Yes   86.8  14.3
  213.                     No    90.9  14.4
  214.         QwriteCV    Yes  111.0  16.8
  215.                     No   119.0  16.8
  216.         QfillC      Yes  244.3  21.5
  217.                     No   176.9  14.0
  218.         Qfill       Yes  246.1  21.5
  219.                     No   177.9  14.0
  220.         Qattr       Yes  177.9  14.0
  221.         QattrC      Yes  177.9  14.0
  222.         QstoreToMem n/a  181.9  13.8
  223.         QstoreToScr n/a  183.9  13.7
  224.  
  225.  
  226.         HOW IT WAS ASSEMBLED:
  227.  
  228.         Turbo compiles some code before and after procedures:
  229.  
  230.           1. 7 bytes before.
  231.           2. 7 bytes after without parameters.
  232.           3. 9 bytes after with parameters.
  233.  
  234.         So, when the modules were assembled, some dummy bytes were placed
  235.         between the procedures to represent Turbo's compiled code which
  236.         allowed Dave Baldwin's Inline to correctly address the calls.
  237.         The dummy bytes were:
  238.  
  239.           Qwrites Module:              Qfills Module:          
  240.               QwriteLV                     QfillC
  241.                 { 16 dummy bytes }           { 16 dummy bytes }
  242.               QwriteV                      Qfill
  243.                 { 16 dummy bytes }           { 16 dummy bytes }
  244.               Qwrite                       QfillsDisp
  245.                 { 16 dummy bytes }           { 14 dummy bytes }
  246.               QwritesDisp                  Qattr
  247.                 { 14 dummy bytes }           { 16 dummy bytes }
  248.               QwriteC                      QattrC
  249.                 { 16 dummy bytes }
  250.               QwriteCV              
  251.  
  252.  
  253.         MODIFICATIONS:
  254.  
  255.         Deleting Procedures - If you want to delete some procedures
  256.         within a module, just follow this simple rule:
  257.  
  258.             Delete from the outside in.
  259.  
  260.         You can delete the procedures surrounding QwriteDisp and
  261.         QfillsDisp, but you cannot for example delete QwriteC without
  262.         also deleting QwriteCV. You of course can delete a whole module.
  263.         Do not attempt to rearrange the procedures within a module unless
  264.         you feel confident with modifying the CALL addresses.
  265.  
  266.         Base Coordinates - If you want to change the upper left corner to
  267.         be 0,0 instead of 1,1, you need to do the following on the inline
  268.         codes described with "Convert to 0-?? range":
  269.  
  270.            1. In QwriteLV, QwriteV, Qwrite, Qfill, and Qattr replace
  271.               DEC DI with NOP which has an inline code of $90.
  272.            2. In QwritesDisp and QfillsDisp, replace DEC DX and DEC AX
  273.               with NOP.
  274.            3. In QwriteC, QwriteCV, QfillC, and QattrC change DEC DI to
  275.               INC DI which has a inline code of $40.
  276.            4. In QstoreToMem and QstoreToScr, replace DEC AX, DEC SI
  277.               and DEC DI with NOP.
  278.  
  279.  
  280.         Qinit.inc - This include file sets up the global variables for the
  281.         Q utilities and was designed for full compatibility with MDA, CGA
  282.         and EGA cards.  You can still modify it to fit your needs.  It is
  283.         not required for the cursor procedures.
  284.  
  285.  
  286.         CREDITS:
  287.  
  288.         Without the assistance and original ideas from Brian Foley
  289.         [76317,3247], these routines would not have been written.  In
  290.         addition, Dave Baldwin's InLine Assembler was essential in its
  291.         development.
  292.  
  293.         Copyright (c) 1986 by Jim LeMay
  294.         These procedures may be used and distributed without profit in
  295.         private contexts.  I must be contacted for any other use.
  296.  
  297.         If there are any problems such as snow, please let me know.
  298.         Jim LeMay [76011,217]  (1-817-735-4833  after 1800 CST )
  299.         6341 Klamath Rd., Ft. Worth, TX, 76116.
  300.  
  301.         APPENDIX:
  302.  
  303.         Quick Reference List of all procedures and parameters:
  304.  
  305.           Qinit;
  306.  
  307.           QwriteLV (Row, Col: byte; Attr, Length: integer; VAR St);
  308.           QwriteV  (Row, Col: byte; Attr: integer; VAR St);
  309.           Qwrite   (Row, Col: byte; Attr: integer; St: Str80);
  310.           QwriteC  (Row, ColL, ColR: byte; Attr: integer; St: Str80);
  311.           QwriteCV (Row, ColL, ColR: byte; Attr: integer; VAR St);
  312.  
  313.           QfillC (Row, ColL, ColR, Rows, Cols: byte; Attr: integer; Ch: char);
  314.           Qfill  (Row, Col, Rows, Cols: byte; Attr: integer; Ch: char);
  315.           Qattr  (Row, Col, Rows, Cols: byte; Attr: integer);
  316.           QattrC (Row, ColL, ColR, Rows, Cols: byte; Attr: integer);
  317.  
  318.           QstoreToMem (Row, Col, Rows, Cols: byte; VAR Dest);
  319.           QstoreToScr (Row, Col, Rows, Cols: byte; VAR Source);
  320.  
  321.           QviewPage  (Page: byte);
  322.           QwritePage (Page: byte);
  323.  
  324.           GotoRC (Row, Col: Byte);
  325.           CursorChange (New: integer; VAR Old: integer);
  326.  
  327.  
  328.         REVISIONS:
  329.  
  330.         Version 1.1 (10-31-86):
  331.            Improved speed about 15%.
  332.            Corrected segment error for Mono mode.
  333.  
  334.         Version 1.2 (11-04-86):
  335.            Added self-centering routines.
  336.            Added document and complete demo.
  337.  
  338.         Version 1.3 (11-10-86):
  339.            Reduced assembly code 60% by using modules.
  340.            Added CursorChange utility.
  341.            Improved speed on Qfill and Qattr about 5%.
  342.            Corrected Qfill bug.  (Extra characters were added when
  343.               attr<0 and Cols=even.)
  344.            Changed EGA detection to use Mono rather than CGA loops.
  345.            Added page capability to GotoRC.
  346.  
  347.         Version 2.0 (11-24-86):
  348.            Complete revision for global access to paging, retrace, and
  349.               segment address.  Permits formats in any column mode (40
  350.               80,120, or whatever).
  351.            Changed Qfill and Qattr for easier Row-by-Column blocks.
  352.            Added QfillC and QattrC for self-centering.
  353.            Added two page utilities.
  354.            Added two screen memory transfer utilities for Row-by-Column
  355.               blocks.
  356.            Increased speed of Qfill with attribute on CGA by 65%.
  357.  
  358.         Version 2.1 (12-09-86):
  359.            Added QwriteLV for partial string writing.
  360.            Added interrupt enable in QwritesDisp and QfillsDisp at
  361.               the end of writing in the vertical band for color.
  362.            Fixed bug in QstoresToScr to access other segments.
  363.            Modified Qdemo.pas for MDA and any column mode.
  364.            Added Qbench.pas to check speed on your own system.
  365.