home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 16 / CD_ASCQ_16_0994.iso / maj / 436 / graphics.doc < prev    next >
Text File  |  1994-06-15  |  76KB  |  1,932 lines
  1.  
  2.  ************************ QLIB GRAPHICS ***********************************
  3.  
  4.   QLIB's graphics subroutines were written initially to provide Hercules
  5.   graphics functions without using QB's QBHERC.COM or MSHERC.COM memory-
  6.   resident drivers, and to provide added capabilities.  Most of these
  7.   subroutines now work in additional graphics modes.  QLIB automatically
  8.   configures itself for the graphics mode in use.
  9.  
  10.   Locations on Graphics screens are defined by coordinate pairs such as (x,y).
  11.   X-coordinates are the horizontal dimensions of the screen, and Y-coordinates
  12.   are the vertical coordinates.  X = 0 is the at the left edge of the screen,
  13.   and X = 719 is the right edge of a Hercules screen, while Y = 0 is the top
  14.   edge of the screen and Y = 347 is the bottom (Hercules).  Thus, the
  15.   coordinate (719,0) is the upper right corner of a Hercules screen.  Maximum
  16.   coordinate values for supported modes are shown on the next page.
  17.  
  18.   You may also use your own coordinate system with QLIB graphics, similar
  19.   to using WINDOW with BASIC's graphics functions.  See QWindow at the
  20.   end of this file.
  21.  
  22.  
  23.  
  24.   QLIB graphics modes are:
  25.  
  26.   Mode           Maximum x   Maximum y    Colors    Equipment
  27.  
  28.   HGraph           719          347       2         Hercules
  29.   HGraph           719          347       16        Hercules InColor
  30.   SCREEN 1         319          199       4         CGA, EGA, MCGA, VGA
  31.   SCREEN 2         639          199       2         CGA, EGA, MCGA, VGA
  32.   SCREEN 3 (1)     719          347       2         Hercules
  33.   SCREEN 4         639          399       2         ATT 6300  (5)
  34.   SCREEN 7         319          199       16        EGA, VGA
  35.   SCREEN 8         639          199       16        EGA, VGA
  36.   SCREEN 9         639          349       16        EGA, VGA  (2)
  37.   SCREEN 10        639          349       4         EGA, VGA  (3)
  38.   SCREEN 11        639          479       2         MCGA, VGA
  39.   SCREEN 12        639          479       16        VGA
  40.   SCREEN 13        319          199       256       MCGA, VGA
  41.   VESA6A           799          599       16        (4)
  42.   XMode16      up to 799     up to 599    16        Super EGA/VGA
  43.   VGA13X       319 or 359    199 to 479   256       VGA
  44.   SVGA16       up to 1024    up to 768    16        Super VGA
  45.   SVGA256      up to 1024    up to 768    256       Super VGA
  46.  
  47.   (1) Requires MSHERC.COM or QBHERC.COM
  48.   (2) EGA with 128k or more memory
  49.   (3) monochrome monitor only
  50.   (4) VESA6A is supported by many Super VGA cards with multi-frequency
  51.       monitors.  See ScreenMode.
  52.   (5) untested mode; should work with any subroutine which supports
  53.       SCREEN 2.  Your feedback, please!
  54.  
  55.   Registered QLIB users may use QLIB's EGAVGA.obj and NOSVGA.obj
  56.   stub files to reduce the size of their .EXE files.  QLIB's stub files
  57.   are similar to the NOEM.obj and NOCOM.obj files supplied by Microsoft
  58.   with QuickBASIC.  EGAVGA eliminates code and data required for monochrome,
  59.   CGA and InColor graphics modes, while NOSVGA eliminates code for Super VGA
  60.   modes.  You must link with the /NOE option when using these stub files.
  61.  
  62.   Example:  I want MYPROG.EXE to support only EGA or VGA 16-color modes
  63.  
  64.   compile: BC MYPROG /O;
  65.   link:    LINK /EX /NOE MYPROG+EGAVGA+NOSVGA,,,QLIB;
  66.  
  67.   linking with EGAVGA.obj reduces .EXE file size by up to 2,630 bytes;
  68.   linking with NOSVGA.obj reduces .EXE size by up to 3,152 bytes.
  69.  
  70. The style% parameter used in many QLIB Graphics subroutines follows these
  71. general rules:
  72.  
  73.     style% =  0 XORs the text/pixel/line/whatever with the pre-existing
  74.                 screen: if a pixel (x,y) is XORed to the screen, the pixel
  75.                 will be turned on if previously off, or will be turned off
  76.                 if previously on;
  77.  
  78.     style% =  1 is normal; lines are drawn, pixels are turned on, text is
  79.                 foreground-on-background, and the previous screen content
  80.                 is ignored or obliterated;
  81.  
  82.     style% =  2 similar to style% 1, but foreground color only is updated
  83.  
  84.     style% =  3 ORs the line or block with the existing screen; this means
  85.                 that the new stuff is added to the old.
  86.  
  87.     style% =  4 ANDs a block (or fillbox) with the existing screen; within
  88.                 the block's limits, only those pixels where both the
  89.                 previous screen and the pattern in the block have ON pixels
  90.                 will there be a resulting ON pixel;
  91.  
  92.     style% = -3 similar to style% 3, but reverses the foreground and
  93.                 background before combining it with the screen
  94.  
  95.     style% = -2 similar to style% 2, but reverses the foreground and
  96.                 background before combining it with the screen
  97.  
  98.     style% = -1 like style% 1, but uses background color.  In monochrome
  99.                 modes, pixels are erased, text is black with a bright
  100.                 background.
  101.  
  102.  
  103.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  104.  
  105.     Subroutine: Bezier(s%, addr%, n%, style%)
  106.     object files: bezier.obj (drawline.obj)
  107.  
  108.         Draws a Bezier curve on the screen.  Data for the curve must
  109.         be in a BezierData data structure (see example in QLIB.BI).
  110.  
  111.         Data required by Bezier:
  112.  
  113.         (x0, y0) = first endpoint
  114.         (x1, y1) = first control point
  115.         (x2, y2) = second control point
  116.         (x3, y3) = second endpoint
  117.         n% = number of points to draw (0 < n% < 32768)
  118.              in most cases, n% = 50 will provide a smooth curve
  119.  
  120.         the control points act as "magnets", pulling the curve away from
  121.         a straight line.  Style% = 0 is not recommended.
  122.  
  123.     Example:
  124.         REM $INCLUDE: 'qlib.bi' ' has BezierData definition
  125.  
  126.         DIM bz AS BezierData    ' standard structure for Bezier curve data
  127.  
  128.         bz.x0 = 140             ' 1st endpoint: (140, 200)
  129.         bz.y0 = 200
  130.         bz.x1 = 0               ' 1st control point
  131.         bz.y1 = 50
  132.         bz.x2 = 600             ' 2nd control point
  133.         bz.y2 = 0
  134.         bz.x3 = 600             ' 2nd endpoint: (600, 300)
  135.         bz.y3 = 300
  136.  
  137.         n% = 200
  138.  
  139.         SCREEN 9
  140.  
  141.         ' show where the endpoints and control points are
  142.         CALL graphcolor(1)
  143.         CALL DrawLine(bz.x0, bz.y0, bz.x1, bz.y1, 1)
  144.         CALL DrawLine(bz.x1, bz.y1, bz.x2, bz.y2, 1)
  145.         CALL DrawLine(bz.x2, bz.y2, bz.x3, bz.y3, 1)
  146.         CALL DrawLine(bz.x3, bz.y3, bz.x0, bz.y0, 1)
  147.  
  148.         CALL graphcolor(15)      ' bright white for the curve
  149.         s% = VARSEG(bz)          ' get data structure address
  150.         a% = VARPTR(bz)
  151.         CALL Bezier(s%, a%, n%, 1)
  152.         IF GetKey THEN SCREEN 0 ' look at it for a while
  153.  
  154.  
  155.  
  156.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  157.  
  158.     Subroutine: BitBlockSave(seg%, x0%, y0%, x1%, y1%)
  159.     Subroutine: BitBlockRestore(seg%, x%, y%, style%)
  160.     object files: bitblock.obj ($graph.obj, bb02.obj, bb04.obj, bb06.obj,
  161.                                 bb08.obj, bb10.obj, bb12.obj, bb14.obj)
  162.  
  163.     Function: bytes% = BitBlockBytes(x0%, y0%, x1%, y1%)
  164.     object files: bbbytes.obj ($graph.obj)
  165.  
  166.     Modes supported: All
  167.  
  168.     BitBlockSave copies a section of the graphics screen to system memory
  169.     in order to copy the block back to the screen later with BitBlockRestore.
  170.  
  171.     BitBlockBytes returns the number of bytes of memory required store
  172.     the entire pixel block.  Bytes% = 0 if the block is too big.  After
  173.     calculating the bytes required, you may use AllocMem(bytes) to
  174.     allocate the memory space required.  See AllocMem in DATA.DOC.
  175.     Note that bit block memory requirements can be large; the huge model
  176.     library QLIBH.LIB is required for large bitblocks in 16-color and
  177.     256-color modes.
  178.  
  179.     style% values supported by BitBlockRestore are:
  180.  
  181.     SCREEN 13, VGA13X, SVGA256:
  182.      1 = replace existing screen area with bit block
  183.      2 = replace existing screen with non-zero pixels in bit block
  184.  
  185.     HGraph (InColor):
  186.      4 = AND the bit block with the existing screen
  187.      3 = OR the bit block with the existing screen
  188.      1,2 = replace existing screen area with bit block
  189.      0 = XOR the bit block with the existing image
  190.     -1,-2 = replace existing screen area with inverse bit block
  191.  
  192.      16-color EGA/VGA-type modes including SVGA16, and SCREEN 10:
  193.       same as InColor, plus:
  194.      -3 = OR the inverse bit block with the existing screen
  195.      -4 = AND the inverse bit block with the existing screen
  196.  
  197.      SCREEN 1, 2, 3, 11, and HGraph (mono):
  198.       2 = combine non-zero pixels in the bit block with the
  199.           pre-existing image
  200.       1 = replace the existing screen image with un-altered
  201.           bit block
  202.       0 = XOR the bit block with the existing image
  203.      -1 = replace existing screen image with inverse bit block
  204.      -2 = combine non-zero pixel in the inverse bit block with
  205.           the previous screen image
  206.  
  207.     See example on next page.
  208.  
  209.     BIT BLOCK EXAMPLE:
  210.  
  211.  
  212.         REM  This example calculates the array size required,
  213.         REM  dimensions the array, saves a portion of the screen and
  214.         REM  restores it later.
  215.  
  216.         REM $INCLUDE: 'qlib.bi'
  217.         REM  start in the desired graphics mode
  218.               .
  219.               .
  220.               .
  221.         x0 = 100: y0 = 0: x1 = 400: y1 = 347
  222.         bytes% = BitBlockBytes(x0%, y0%, x1%, y1%)
  223.         REM  Note that huge model BitBlockBytes returns a LONG integer
  224.         bbseg% = AllocMem(bytes%)
  225.         CALL BitBlockSave(bbseg%, x0%, y0%, x1%, y1%)
  226.               .
  227.               .
  228.               .
  229.         REM  now we'll copy the block back to the screen
  230.         CALL BitBlockRestore(bbseg%, x2%, y2%, style%)
  231.         REM  x2% and y2% may be any coordinates on the screen
  232.         REM  also release the memory block
  233.         CALL FreeMem(bbseg%)
  234.  
  235.  
  236.     If you do not intend to support all QLIB graphics modes, you can
  237.     call mode-specific BitBlock subroutines to reduce .EXE size.
  238.     These subroutines use the same calling parameters as BitBlockSave
  239.     and BitBlockRestore:
  240.  
  241.     (save bit block)
  242.  
  243.     getbb02: SCREEN 1-4, SCREEN 11, HGraph (mono and InColor)
  244.     getbb06: SCREEN 7-10, SCREEN 12, SVGA16(0), XMODE16
  245.     getbb08: SCREEN 13
  246.     getbb10: VGA13X
  247.     getbb12: SVGA16
  248.     getbb14: SVGA256
  249.  
  250.     (restore bit block)
  251.  
  252.     putbb02: SCREEN 1-4, SCREEN 11, HGraph (mono only)
  253.     putbb04: HGraph (InColor only)
  254.     putbb06: SCREEN 7-10, SCREEN 12, SVGA16(0), XMODE16
  255.     putbb08: SCREEN 13
  256.     putbb10: VGA13X
  257.     putbb12: SVGA16
  258.     putbb14: SVGA256
  259.  
  260.  
  261.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  262.  
  263.     Subroutine: BitPlaneSave(seg%, x0%, y0%, x1%, y1%, plane%)
  264.     Subroutine: BitPlaneRestore(seg%, x0%, y0%, style%, plane%)
  265.     object files: same as BitBlockRestore and BitBlockSave
  266.  
  267.     Function: bytes% = BitPlaneBytes(x0%, y0%, x1%, y1%)
  268.     object files: bbbytes.obj ($graph.obj)
  269.  
  270.     Modes supported: HGraph (InColor)
  271.                      SCREEN 7,8,12
  272.                      SCREEN 9  (requires 128k+ EGA memory)
  273.                      VESA6A, XMode16
  274.                      SCREEN 10 (planes 0 and 2)
  275.  
  276.     BitPlaneSave subroutines copy a section of the graphics screen to a
  277.     memory buffer in order to copy that block back to the screen with
  278.     BitPlaneRestore.  This is similar to the BitBlockSave/BitBlockRestore
  279.     subroutines, except that BitPlane subroutines copy to or from only one
  280.     of the four "planes" of memory in 16-color modes.  This is handy when
  281.     the area you want to copy is too big to fit in one array, or when you
  282.     want to move or modify only one plane at a time.  The exact color
  283.     represented by each plane is determined by PALETTE or COLOR statements.
  284.  
  285.     BitPlaneBytes calculates the number of bytes of memory required to save
  286.     the desired portion of the plane.  All style% values work with
  287.     BitPlaneRestore.  You may use AllocMem(bytes%) to allocate memory
  288.     space for the bit plane.
  289.  
  290.     Example:
  291.          REM $INCLUDE: 'qlib.bi'
  292.          REM  calculate the array size required, allocate the memory,
  293.          REM  save a portion of one plane of the screen and restores it later.
  294.          REM  note that valid plane numbers are 0 - 3
  295.  
  296.          REM  First I need to establish graphics mode
  297.          CALL Xmode16(xmode%, maxX%, maxY%)
  298.               .
  299.               .
  300.          x0 = 100: y0 = 0: x1 = 400: y1 = 347
  301.          bytes% = BitPlaneBytes(x0%, y0%, x1%, y1%)
  302.          seg% = AllocMem(bytes%): plane% = 0
  303.          CALL BitPlaneSave(seg%, x0%, y0%, x1%, y1%, plane%)
  304.               .
  305.               .
  306.          REM  now we'll copy the plane back to the screen
  307.          CALL BitPlaneRestore(seg%, x2%, y2%, style%, plane%)
  308.  
  309.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  310.  
  311.     Subroutine: ClearView
  312.     object files: clrview.obj ($graph.obj, $horiz.obj)
  313.  
  314.     Modes supported: All
  315.  
  316.        ClearView erases everything within the active viewport.  In
  317.     color modes, the background color set by GraphColor is used.  Use
  318.     SetView to establish the active viewport.
  319.  
  320.     Example:
  321.       CALL ClearView
  322.  
  323.  
  324.  
  325.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  326.  
  327.      Function: colorvalue% = Color16(red%, green%, blue%)
  328.      object file: color16.obj
  329.  
  330.      supports EGA and VGA 16-color modes
  331.  
  332.           Color16 calculates a color value from individual red, green and
  333.      blue intensities, for changing the color palette in 16-color modes
  334.      (text or graphics).  Used with Palette16.  Red%, green% and blue%
  335.      range from 0 (off) to 3 (highest intensity).
  336.  
  337.      Example:  see Palette16
  338.  
  339.  
  340.  
  341.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  342.  
  343.      Function: colorvalue& = Color256&(red%, green%, blue%)
  344.      object file: color256.obj
  345.  
  346.      Supports all VGA and SVGA 256-color modes
  347.  
  348.           Color256& returns a LONG INTEGER color value from individual
  349.      red% green% and blue% components for changing palette colors in
  350.      256-color modes.  Color256& changes the actual color associated
  351.      with a particular color attribute.  With Color256&, red, green and
  352.      blue color intensitites may range from 0 (off) to 63 (highest intensity).
  353.  
  354.      Example:  see Palette256
  355.  
  356.  
  357.  
  358.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  359.  
  360.     Subroutine: DrawBox(x0%, y0%, x1%. y1%, style%)
  361.     object file: drawbox.obj ($graph.obj, $horiz.obj, $vert.obj)
  362.  
  363.     Modes supported: All
  364.  
  365.          DrawBox draws a box with corners at (x0%, y0%), (x0%, y1%),
  366.     (x1%, y0%), (x1%, y1%).  Legal style% parameters are -1, 0, and 1.
  367.     If any part of the box lies outside the active graphics viewport,
  368.     that part of the box will not be drawn.  See also LinePattern.
  369.  
  370.     Example:
  371.          CALL HGraph
  372.          x0% = 10: y0% = 10: x1% = 79: y1% = 38: style% = 0
  373.          CALL DrawBox(x0%, y0%, x1%, y1%, style%)
  374.  
  375.  
  376.  
  377.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  378.  
  379.     Subroutine: DrawCircle(xc%, yc%, Xradius%, style%)
  380.     Subroutine: CircleAspect(numerator%, denominator%)
  381.     object files: drawcirc.obj ($graph.obj, $putdot.obj)
  382.  
  383.     Modes supported: All
  384.  
  385.        DrawCircle draws a circle on a graphics screen centered at xc%, yc%,
  386.     with x-radius Xradius%.  The circle's aspect ratio may be changed with
  387.     CircleAspect.  Legal style% parameters are -1, 0 and 1 with monochrome
  388.     modes.  In color modes, style% parameters 2, -2, 3 and -3 are also
  389.     supported. Only the part of the circle which lies within the viewport
  390.     defined by SetView will be drawn.
  391.  
  392.     CircleAspect changes the aspect ratio of the circle; using CircleAspect,
  393.     you can make the circle look like a flattened ellipse or a tall ellipse.
  394.     CircleAspect changes the Y-dimension of the circle; the X-dimension is
  395.     controlled with Xradius%.  QLIB's default is an aspect ratio of 1:1.
  396.     CAUTION: extreme aspect ratios are not supported by DrawCircle.
  397.     With numerator% = 1, a maximum usable denominator% is 5, or else a
  398.     "divide by zero" error will occur.  With denominator% = 1, a high
  399.     numerator will cause unpredictable results.
  400.  
  401.     Example:
  402.          CALL DrawCircle(xc%, yc%, Xradius%, style%)
  403.  
  404.  
  405.  
  406.  
  407.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  408.  
  409.     Subroutine: DrawLine(x0%, y0%, x1%, y1%, style%)
  410.     object files: drawline.obj ($graph.obj, $horiz.obj, $vert.obj
  411.                                 $loslope.obj, $hislope.obj)
  412.  
  413.     Modes supported: All
  414.  
  415.        DrawLine draws a line from x0%, y0% to x1%, y1%.  Legal style
  416.     parameters are -4 through 4.  See also LinePattern.
  417.  
  418.     Example:
  419.          x0% = 0: y0% = 0: x1% = 719: y1% = 348: style% = -1
  420.          CALL DrawLine(x0%, y0%, x1%, y1%, style%)
  421.          REM this erases a diagonal line across the screen
  422.  
  423.  
  424.  
  425.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  426.  
  427.    Subroutine: FillArea(x%, y%, reserved%)
  428.    object files: fillarea.obj ($graph.obj, $horiz.obj, fpattern.obj)
  429.  
  430.    Modes supported: All
  431.  
  432.          FillArea fills irregularly-shaped areas enclosed by solid lines.
  433.     FillArea works best with SIMPLE areas; holes in the area or areas with
  434.     "inside" corners dividing horizontal lines may not be filled properly.
  435.     Further development is planned, but FillArea in its present form is
  436.     useful in many circumstances.  FillArea works by starting at the seed
  437.     pixel (x%, y%) and looking left and right for non-black region boundaries,
  438.     then filling horizontal lines between the boundaries.  FillArea works
  439.     upward until the top of the area has been reached, then returns to the
  440.     seed pixel and works downward.  Reserved% is reserved for QLIB's style%
  441.     parameter.  FillArea presently assumes style% = 1.  If you want to fill
  442.     rectangular areas, FillBox is much faster than FillArea.
  443.  
  444.     Example:
  445.          CALL HGraph
  446.               .
  447.               .
  448.               .
  449.          CALL GraphColor(attr%)             ' for color modes
  450.          CALL FillPattern(pattern$)         ' optional fill pattern
  451.          CALL FillArea(x%, y%, reserved%)
  452.  
  453.  
  454.  
  455.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  456.  
  457.     Subroutine: FillBox(x0%, y0%, x1%. y1%, style%)
  458.     object files: fillbox.obj ($graph.obj, $horiz.obj)
  459.  
  460.     Modes supported: All
  461.  
  462.        Similar to DrawBox, FillBox uses the same coordinates and style
  463.     variable, but fills the box instead of drawing the sides.  If
  464.     style% = 1 or 2, an optional pattern may be used to fill the box
  465.     (except SCREEN 1).  See FillPattern.
  466.  
  467.     Example:
  468.       CALL HGraph
  469.          x0% = 10: y0% = 10: x1% = 79: y1% = 38: style% = 0
  470.          CALL FillBox(x0%, y0%, x1%, y1%, style%)
  471.  
  472.  
  473.  
  474.  
  475.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  476.  
  477.     Subroutine: FillPattern(pattern$)
  478.     object files: fpattern.obj ($horiz.obj, $graph.obj)
  479.  
  480.     Modes supported: HGraph (mono annd InColor)
  481.                      VESA6A, XMode16, SVGA16
  482.                      SCREEN 2,3,7,8,9,10,11,12
  483.  
  484.         FillPattern defines an optional pattern used by FillBox if
  485.     style% >= 1,  or by FillArea (which assumes style% = 1). The bit
  486.     patterns in the first 8 characters of pattern$ are used to modify the
  487.     fill in the box or area.  FillPattern must be called before each call
  488.     to FillBox or FillArea.  See Examples.  FillBox will replace box borders.
  489.     If you want the box to have a solid outline, call DrawBox with style% = 1
  490.     after using FillBox with a pattern.  Using style% = 1, the pattern will
  491.     completely replace whatever was in the box.  16-color modes use
  492.     style% = 2.  BIT2INT in DATA.DOC is useful for establishing patterns.
  493.  
  494.     Sample patterns, and what they produce:
  495.  
  496.     pattern$ = CHR$(255) + STRING$(5,32)    ' produces a pattern of squares
  497.     pattern$ = STRING$(8,32)                ' produces vertical lines
  498.     pattern$ = CHR$(255) + STRING$(5,0)     ' produces horizontal lines
  499.  
  500.     pattern$ = STRING$(8,0): k% = 1
  501.     FOR i% = 1 TO 8
  502.          MID$(pattern$, i%) = CHR$(k%)
  503.          CALL ShiftINT(k%, 1)
  504.     NEXT i%                                 ' produces diagonal lines, from 
  505.                                             ' upper right to lower left
  506.     pattern$ = STRING$(8,0):k% = 128
  507.     FOR i% = 1 TO 8
  508.          MID$(pattern$, i%) = CHR$(k%)
  509.          CALL ShiftINT(k%, -1)
  510.     NEXT i%                                 ' produces diagonal lines, from
  511.                                             ' upper left to lower right
  512.  
  513.     Example:
  514.       x0% = 10: y0% = 10: x1% = 79: y1% = 38: style% = 1
  515.       pattern$ = CHR$(255) + STRING$(5,32)        ' pattern for squares
  516.       CALL FillPattern(pattern$)
  517.       CALL FillBox(x0%, y0%, x1%, y1%, style%)    ' fill box with pattern
  518.       CALL DrawBox(x0%, y0%, x1%, y1%, style%)    ' draw solid box outline
  519.       CALL FillArea(x%, y%, reserved%)            ' no pattern used
  520.                                                   ' because FillPattern
  521.                                                   ' was not called before
  522.                                                   ' FillArea
  523.  
  524.  
  525.  
  526.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  527.  
  528.     Subroutine: FontWidth(pixels%)
  529.     object files: fwidth.obj (f8x14.obj)
  530.  
  531.     Modes supported: All
  532.  
  533.     GPrint subroutines' default character width is 8 pixels.  FontWidth
  534.     changes the number of pixels per character, permitting compressed
  535.     or expanded GPRINTing.  When using fonts less than 8 pixels wide,
  536.     FontWidth can be used to make GPRINT to space the characters properly.
  537.  
  538.     GPRINT prints 8-pixel wide characters no matter what FontWidth is;
  539.     FontWidth changes the spacing from the left side of one character to
  540.     the left side of the next.
  541.  
  542.     Example:
  543.  
  544.     DEFINT A-Z
  545.     CALL GPrint("normal character spacing",10,10,1)
  546.     CALL FontWidth(10)
  547.     CALL GPrint(" 10-pixel character spacing",10,30,1)
  548.  
  549.  
  550.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  551.  
  552.     Subroutine: GBaseSeg (s%)
  553.     object files: gbaseseg.obj ($graph.obj)
  554.  
  555.     Modes supported: HGraph (monochrome only)
  556.                      SCREEN 1,2,3,4,11,13
  557.  
  558.     GBaseSeg re-directs QLIB's Graphics subroutines to an alternate buffer.
  559.     This may be used to duplicate the effect of multiple screen pages.
  560.     GBaseSeg works only with non-planar, non-bank switched modes.
  561.     S% is the segment base address of the alternate buffer.  QLIB assumes
  562.     that the buffer begins at the start of the segment.  If you call
  563.     GBaseSeg with s% = 0, the default video buffer becomes active again.
  564.  
  565.     Note that GBaseSeg will not work if you change graphics modes after
  566.     calling GBaseSeg.
  567.  
  568.     When operating under a multi-tasking enviornment, such as DesqView,
  569.     GBaseSeg may also work with any mode supported by the multi-task
  570.     control program.  Feedback, please!
  571.  
  572.     Example on next page
  573.  
  574.  
  575.     REM GBaseSeg example
  576.  
  577.     REM $INCLUDE: 'qlib.bi'
  578.  
  579.     ' load existing screen image to RAM buffer
  580.         gpd = fload("screen13.gph")
  581.  
  582.     ' switch to graphics mode
  583.         SCREEN 13
  584.  
  585.     ' after switching to graphics mode, tell QLIB
  586.     ' where the off-screen buffer is
  587.         CALL gbaseseg(gpd)
  588.  
  589.     ' modify the off-screen image as desired
  590.         CALL GraphColor(10)
  591.         CALL DrawLine(0, 199, 319, 0, 1)
  592.         CALL gprint("this was printed to an off-screen buffer", 0, 60, 2)
  593.  
  594.     ' switch back to video buffer and print a message
  595.         CALL gbaseseg(0)
  596.         CALL gprint("press any key...", 0, 0, 1)
  597.         a = getkey
  598.  
  599.     ' copy the modified alternate buffer to the video buffer
  600.     ' NOTE: Video buffer address and size vary depending on graphics mode:
  601.     '
  602.     '  mode      address  size (bytes)
  603.     '
  604.     ' SCREEN 1   &HB800   16384
  605.     ' SCREEN 2   &HB800   16384
  606.     ' SCREEN 3   &HB000   32768
  607.     ' HGraph     &HB000   32768
  608.     ' SCREEN 4   &HB800   32768
  609.     ' SCREEN 11  &HA000   38400
  610.     ' SCREEN 13  &HA000   64000
  611.  
  612.         bytes& = 64000
  613.         CALL CopyMem(gpd, 0, &HA000, 0, bytes&, 0)
  614.  
  615.     ' release the alternate buffer 'cuz I'm all done with it
  616.     ' then wait for a keypress and exit
  617.         CALL freemem(gpd)
  618.         IF getkey THEN SCREEN 0
  619.         END
  620.  
  621.  
  622.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  623.  
  624.     Subroutine: GCopy(frompage%, topage%, oops%)
  625.     object files: gcopy.obj ($graph.obj)
  626.  
  627.     Modes supported: HGraph (mono and InColor)
  628.                      VGA13X (0 - 2)
  629.                      SCREEN 3,7,8,9,10
  630.  
  631.         Similar to BASIC's PCOPY command, GCopy copies one page of
  632.     graphics memory to another, but returns an error flag instead of
  633.     requiring ON ERROR to trap errors.  GCopy also works with many VGA13X
  634.     modes.  oops% = 0 if no error, or -1 if GCopy is not supported or
  635.     if either frompage% or topage% is too large.
  636.  
  637.     Example:
  638.         frompage% = 0: topage% = 1
  639.         CALL GCopy(frompage%, topage%, oops%)
  640.  
  641.  
  642.  
  643.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  644.  
  645.     Subroutine: GetDot(x%, y%, value%)
  646.        (formerly GetPixel)
  647.     object file: getdot.obj ($graph.obj, $getdot.obj)
  648.  
  649.     Modes supported: All
  650.  
  651.          Determines the color of the pixel located at (x%, y%).
  652.     Returns value% = -1 if (x%,y%) falls outside the active graphics
  653.     viewport.
  654.  
  655.     Example:
  656.          x% = 0: y% = 0
  657.          CALL GetDot(x%, y%, value%)
  658.          REM  This will determine the color of the pixel at the upper left
  659.          REM  corner of the screen.
  660.  
  661.  
  662.  
  663.  
  664.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  665.  
  666.     Subroutine: GraphColor(attr%)
  667.     object files: gcolor.obj ($graph.obj)
  668.  
  669.     Modes supported: HGraph (InColor)
  670.                      VESA6A, XMode16, VGA13X, SVGA16, SVGA256
  671.                      SCREEN 1,7,8,9,10,12,13
  672.  
  673.         Sets the color attribute to be used when QLIB subroutines are
  674.     used in color modes.  Color attributes for 16-color modes may be
  675.     calculated with ColorAttr (See VIDEO.DOC).
  676.  
  677.  
  678.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  679.  
  680.     Subroutine: GCursor(x%, y%)
  681.     Subroutine: GUCursor(x%, y%)
  682.     object file: gcursor.obj ($graph.obj, $putdot.obj)
  683.  
  684.     Modes supported: All
  685.  
  686.        GCursor subroutines put a text cursor on graphics screens
  687.     at the character box with upper left coordinates at x%, y%.
  688.     GCursor and GUCursor subroutines are similar to QLIB's text-mode
  689.     CursorON and UCursorON subroutines, except that GCursor waits until
  690.     a key has been pressed before returning to QuickBASIC.  The key
  691.     pressed may be determined with QLIB's input subroutines, or with
  692.     QB's INKEY$ function.  In HGraph, SCREEN 9, 10, or 12, GCursor
  693.     subroutines work with either normal text or QLIB's small text.  To use
  694.     GCursor with text printed by BASIC, see example 2.
  695.  
  696.     Example 1:
  697.          CALL HGraph
  698.          a$ = "I want a cursor at the 'I' at the start of this line"
  699.          x% = 5: y% = 3: style% = 1
  700.          CALL GPrint(a$, x%, y%, style%)
  701.          CALL GCursor(x%, y%)
  702.  
  703.     Example 2:
  704.          SCREEN 3                           ' uses QBHERC.COM or MSHERC.COM
  705.          CALL StdText                       ' make sure the BIOS data area
  706.                                             ' has been updated
  707.          row% = 10: column% = 3
  708.          LOCATE row%, column%: PRINT a$     ' use QB to print text
  709.          x% = (column% - 1) * 9             ' this example is for a
  710.          y% = (row% - 1) * 14               ' QBHERC 9x14 character box
  711.          CALL GCursor(x%, y%)
  712.  
  713.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  714.  
  715.     Subroutine: GMouse
  716.     object files: gmouse.obj (mousedat.obj, $graph.obj)
  717.  
  718.     GMouse initializes the alternate graphics mouse cursor driver.
  719.     After calling GMouse, QLIB's alternate mouse cursor may be used in
  720.     any graphics mode supported by QLIB.  This is nessesary because most
  721.     mouse drivers do not recognize modes other than those supported by
  722.     IBM-brand equipment (such as Hercules, InColor, ATT, VGA13X, SVGA,
  723.     xmode16).
  724.  
  725.     The GMouse cursor has some limitations: it wraps around to the left
  726.     side of the screen if it gets within 13 bytes of the right edge, it
  727.     does not (yet) respond to QLIB's MouseLimit subroutine, and it must
  728.     first be hidden with HideGMouse before using MousePos.  GMouse works
  729.     with these QLIB mouse subroutines:
  730.  
  731.      MouseStatus   KeyOrButton   HideGMouse   ShowGMouse   MousePos
  732.  
  733.     Any time you change graphics modes, you must re-initialize GMouse.
  734.     Turn GMouse off with HideGMouse before you switch back to text mode.
  735.  
  736.     Example:
  737.        REM $INCLUDE: 'qlib.bi'    ; has declaration for IsMouse
  738.  
  739.       ' enter desired graphics mode before calling GMouse
  740.        svgaOK = SVGA256(3)
  741.        IF IsMouse THEN CALL GMouse: CALL ShowGMouse
  742.         .
  743.         .
  744.         .
  745.       ' move the mouse cursor to new location
  746.        CALL HideGMouse
  747.        CALL MousePos(x%, y%)
  748.        CALL ShowGMouse
  749.  
  750.  
  751.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  752.  
  753.     Subroutines: HGraph, HGraph0
  754.     object files: hgraph.obj (q$herc.obj, hmode.obj)
  755.  
  756.     Subroutine: HText
  757.     object files: hmode.obj (q$herc.obj)
  758.  
  759.     Requires Hercules (mono or InColor)
  760.  
  761.         These subroutines change modes on the Hercules graphics card,
  762.     without using QBHERC.COM.  If you use HGraph to set graphics mode,
  763.     QuickBASIC video input/output functions will not work, and you must use
  764.     HText to restore text mode.  QB2/QB3/QB87 users MUST use HGraph to use
  765.     Hercules graphics.  HText resets the active page to 0.  (See UseTPage in
  766.     VIDEO.DOC).  HGraph clears the entire video buffer; HGraph0 clears only
  767.     page 0.
  768.  
  769.     With HGraph0, anything in graph page 1 is undisturbed.  A graph may
  770.     be stored in page 1, the system can be switched back to text mode for a
  771.     while, and if text page 8 - 15 are not used, the graph may be restored
  772.     by calling HGraph0 and GCopy(1, 0, oops%).
  773.  
  774.     HGraph0 can also be used if text screens are stored in pages 8 - 15.
  775.     As long as graph page 1 is not used, the text screens will not be
  776.     disturbed and can be restored with HText and TCopy.
  777.  
  778.     If you are using Hercules graphics in a 2-monitor system, use HGraph0.
  779.     HGraph0 and HText will make the Monochrome monitor the default; to
  780.     use the color monitor, call ModeColor (See VIDEO.DOC).
  781.  
  782.     Example:
  783.          CALL HGraph         ' establishes Hercules Graphics mode
  784.                              ' QLIB graphics subroutines will work properly
  785.          CALL HText          ' returns Hercules system to text mode
  786.  
  787.  
  788.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  789.  
  790.     Subroutine: GCenter(st$, y%, style%)
  791.     object files: gcenter.obj ($graph.obj, gprint.obj, $gp.obj, f8x14.obj)
  792.  
  793.     GCenter prints text on a graphics screen, centered horizontally.
  794.     This subroutine calculates the correct x-coordinate, then calls
  795.     GPrint.  GCenter supports all style% parameters and graphics
  796.     modes supported by GPrint.
  797.  
  798.     Example:
  799.         REM  I want to center a graph title at the top of the screen
  800.         y% = 0                   ' top of screen
  801.         style% = 1: title$ = "Graph Title"
  802.         CALL GCenter(title$, y%, style%)
  803.  
  804.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  805.  
  806.     Subroutine: GCenterX(st$, y%, style%)
  807.     object files: gcenterx.obj ($graph.obj, gprintx.obj, $gp.obj, f8x14.obj)
  808.  
  809.     GCenterX prints double-width text on a graphics screen, centered
  810.     horizontally.  This subroutine calculates the correct x-coordinate,
  811.     then calls GPrintX.  GCenterX supports all style% parameters and
  812.     graphics modes supported by GPrintX.
  813.  
  814.     Example:
  815.         REM  I want to center a graph title at the top of the screen
  816.         y% = 0                   ' top of screen
  817.         style% = 1
  818.         title$ = "Graph Title"
  819.         CALL GCenterX(title$, y%, style%)
  820.  
  821.  
  822.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  823.  
  824.     Subroutine: GLineEdit(st$, x%, y%, style%, options%, keycode%)
  825.     object files: gedit.obj (q$edit.obj, gcursor.obj, gprint.obj)
  826.  
  827.     Modes supported: All
  828.  
  829.       GLineEdit works like LineEdit (see INPUT.DOC), but is usable in
  830.     graphics modes.  GLineEdit uses all LineEdit options except 8 (BIOS
  831.     display) and -32768 (alternate cursor).  All LineEdit editing commands,
  832.     as well as StartEdit and LastEdit, work properly with GLineEdit.
  833.     GLineEdit also works fine with SmallText.  See LineEdit for examples.
  834.     Style% 1 and -1 work best.
  835.  
  836.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  837.  
  838.     Subroutine: GLoad(filename$, oops%)
  839.     Subroutine: GSave(filename$, oops%)
  840.     object files: gsave.obj ($graph.obj, $asciiz.obj, $gbytes.obj)
  841.  
  842.     Modes supported: All
  843.  
  844.        GLoad loads a Graphics screen from a file to the screen.  The file
  845.     must have been previously saved by GSave.  GLoad and GSave load to or
  846.     save from the active graphics page.  If no error occurred, oops% = 0.
  847.     Oops% will be an MS-DOS error code if a file handling error occurs.
  848.     See the introductory remarks in DISK.DOC for MS-DOS error codes.
  849.  
  850.     NOTE: files created by GSave eat lots of disk space:
  851.  
  852.          HGraph  (mono)      32,768 bytes
  853.          HGraph  (InColor)  131,072 bytes
  854.          VGA13X(0)           64,000 bytes
  855.          VGA13X(1)           76,800 bytes
  856.          VGA13X(2)          128,000 bytes
  857.          VGA13X(3)          172,800 bytes
  858.          XMode16      up to 240,000 bytes
  859.          VESA6A, SVGA16(0)  240,000 bytes
  860.          SVGA16(1)          393,216 bytes
  861.          SVGA256(0)         256,000 bytes
  862.          SVGA256(1)         307,200 bytes
  863.          SVGA256(2)         480,000 bytes
  864.          SVGA256(3)         786,432 bytes
  865.          SCREEN 1, 2         16,384 bytes
  866.          SCREEN 3, 4         32,768 bytes
  867.          SCREEN 7            32,000 bytes
  868.          SCREEN 8            64,000 bytes
  869.          SCREEN 9           112,000 bytes
  870.          SCREEN 10           56,000 bytes
  871.          SCREEN 11           38,400 bytes
  872.          SCREEN 12          153,600 bytes
  873.          SCREEN 13           64,000 bytes
  874.  
  875.     Example:
  876.         filename$ = "BARGRAPH.HGC"
  877.         CALL GSave(filename$, oops%)
  878.  
  879.  
  880.  
  881.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  882.  
  883.     Subroutine: GLoadEMS(handle%)
  884.     Function: handle% = GSaveEMS
  885.     object files: gsaveems.obj ($graph.obj, $emspage.obj, ems.obj,
  886.                                 $gbytes.obj, banks.obj)
  887.  
  888.     Modes supported: All
  889.  
  890.        Similar to GLoad and GSave; GSaveEMS saves a Graphics screen in
  891.     EMS memory, and GLoadEMS copies from EMS to the screen.  These
  892.     subroutines assume that EMS memory is installed; see IsEMS in EMSXMS.DOC
  893.     to detect EMS memory.  GSaveEMS allocates a block of EMS memory, copies
  894.     the screen to EMS, and returns a handle for subsequent access to the
  895.     memory block.  Multiple screens may be stored if sufficient EMS memory
  896.     is available.  When you are done using the stored screen, call
  897.     FreeEMS(handle%) to release the EMS memory.  If you do not release the
  898.     EMS block before your program ends, that memory will not be available
  899.     to other programs.  See FreeEMS in EMSXMS.DOC.  GSaveEMS and GLoadEMS
  900.     return EMS error status in EMSError (see EMSXMS.DOC).
  901.   
  902.     Example:
  903.         REM $INCLUDE: 'qlib.bi'
  904.            .
  905.            .
  906.            .
  907.         REM assume system in graphics mode
  908.         IF IsEMS THEN
  909.              handle% = GSaveEMS
  910.              IF EMSError GOTO UseFile
  911.              SavedInEMS = 1                 ' turn program's EMS flag on
  912.              SavedAsFile = 0                ' turn program's file flag off
  913.              ELSE
  914. UseFile:
  915.              REM  save the screen to disk file if EMS not available
  916.              filename$ = "BARGRAPH.HGC"
  917.              CALL GSave(filename$, oops%)
  918.              SavedAsFile = 1: SavedAsEMS = 0
  919.         ENDIF
  920.            .
  921.            .
  922.            .
  923.            .
  924.  
  925.         REM  later ...
  926.         IF SavedAsEMS THEN
  927.              CALL GLoadEMS(handle%)
  928.              IF NOT EMSError THEN CALL FreeEMS(handle%)
  929.              ELSE
  930.              CALL GLoad(filename$, oops%)
  931.              IF NOT oops% THEN CALL KillFile(filename$, oops%)
  932.         ENDIF
  933.  
  934.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  935.  
  936.     Subroutine: GPage(page%, oops%)
  937.     object files: gpage.obj ($graph.obj, q$herc.obj)
  938.  
  939.     Modes supported: HGraph (mono and InColor)
  940.                      VGA13X(0 - 2)
  941.                      SCREEN 7,8
  942.                      SCREEN 9,10    (256k EGA memory)
  943.  
  944.         GPage combines the function of UseGPage and ShowGPage; see UseGPage
  945.     and ShowGPage for further information.
  946.  
  947.     Example:
  948.         CALL GPage(page%, oops%)
  949.         REM this is equivalent to
  950.         REM  CALL UseGPage(page%, oops%)
  951.         REM  CALL ShowGPage(page%, oops%)
  952.  
  953.  
  954.  
  955.  
  956.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  957.  
  958.     Subroutine: GPrint(st$, x%, y%, style%)
  959.     object files: gprint.obj ($graph.obj, $gp.obj, f8x14.obj)
  960.  
  961.     Modes supported: All (SCREEN 1, style% 1 and -1 only)
  962.  
  963.     GPrint offers much more flexibility than BASIC's PRINT command when
  964.     printing text on a graphics screen, and it's the only way to put text
  965.     on a Hercules graphics screen if MSHERC is not loaded.  GPrint prints
  966.     a string of text anywhere on the screen in normal, reverse video, XOR
  967.     or "foreground only" modes.  GPrint is also much faster than QB's PRINT
  968.     command in graphics modes.
  969.  
  970.     The size of each character and the number of characters across the
  971.     screen depends on the graphics mode:
  972.  
  973.     mode              standard character size    columns
  974.  
  975.     HGraph & SCREEN 3     8 x 14                    90
  976.     SCREEN 1, 7, 13       8 x 8                     40
  977.     SCREEN 2, 8           8 x 8                     80
  978.     SCREEN 4, 9,10,11,12  8 x 14                    80
  979.     VGA13X(0-2)           8 x 14                    40
  980.     VGA13X(3)             8 x 14                    45
  981.     VESA6A, SVGA16(0)     8 x 14                   100
  982.     XMode16               8 x 14                  varies
  983.     SVGA16(1), SVGA256(3) 8 x 14                   128
  984.     SVGA256(0 or 1)       8 x 14                    80
  985.     SVGA256(2)            8 x 14                   100
  986.  
  987.     All ASCII characters may be used.  x% and y% are the PIXEL locations of
  988.     the upper left corner of the first character.  SmallText, below, allows
  989.     GPrint to use the smaller 8 x 8 character in Hercules, VESA6A, XMode16,
  990.     SCREEN 9-12 and SVGA modes.  Legal style% values are -2, -1, 0, 1 and 2.
  991.  
  992.     In modes with 8 x 8 characters, you must call SmallText sometime
  993.     before calling GPrint if you use characters greater than CHR$(127).
  994.  
  995.     To calculate how many rows of text a graphics screen can display,
  996.     divide maximum Y by pixel rows (i.e., a Hercules screen can display
  997.     347/8 = 43 rows of text in SmallText mode).
  998.  
  999.     Example:
  1000.       st$ = "This is an example of text in graphics mode"
  1001.       x% = 10: y% = 20: CALL GPrint(st$, x%, y%, style%)
  1002.  
  1003.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1004.  
  1005.     Subroutine: GPrintDOWN(st$, x%, y%, style%)
  1006.     Subroutine: GPrintUP(st$, x%, y%, style%)
  1007.     object files: gprint.obj (q$graph.obj, $gp.obj, f8x14.obj)
  1008.  
  1009.     Modes supported: same as GPrint
  1010.  
  1011.     GPrintUP rotates the string so that text reads from the bottom of
  1012.     the screen to the top.  This is useful for labeling the vertical axis of
  1013.     a graph, among other things.  GPrintDOWN reads from the top of the
  1014.     screen to the bottom.  These subroutines use SmallText's 8 x 8 character
  1015.     box, allowing up to 43 characters from the bottom of the screen to the
  1016.     top in Hercules mode.  If you are going to use characters greater than
  1017.     CHR$(127), you must call SmallText some time in your program before
  1018.     calling GPrintDOWN/UP.  However, QLIB does not need to be in SmallText
  1019.     mode when you call GPrintDOWN or GPrintUP.    All GPrint style% values are
  1020.     valid.
  1021.  
  1022.     Example:
  1023.          DEFINT a - z
  1024.          CALL HGraph
  1025.          CALL SmallText             ' let GPrintUP know where to find
  1026.              .                      ' character definitions > CHR$(127)
  1027.              .
  1028.              .
  1029.          CALL GPrintUP(text$, x%, y%, style%)
  1030.  
  1031.  
  1032.  
  1033.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1034.  
  1035.     Subroutine: GPrintX(st$, x%, y%, style%)
  1036.     Subroutine: GPrint2X(st$, x%, y%, style%)
  1037.     Subroutine: GPrintDOWNX(st$, x%, y%, style%)
  1038.     Subroutine: GPrintDOWN2X(st$, x%, y%, style%)
  1039.     Subroutine: GPrintUPX(st$, x%, y%, style%)
  1040.     Subroutine: GPrintUP2X(st$, x%, y%, style%)
  1041.     object files: gprintx.obj (q$graph.obj, $gp.obj, f8x8.obj)
  1042.  
  1043.     Modes supported: same as GPrint
  1044.  
  1045.        GPrintX subroutines are similar to GPrint, GPrintUP and GPrintDOWN,
  1046.     except each character in st$ is expanded to twice its normal horizontal
  1047.     size before printing it on the screen; this is handy for graph headings.
  1048.     GPrint2X subroutines expand each character horizontally and vertically;
  1049.     All graphics modes and styles supported by GPrint work fine with these
  1050.     expanded character subroutines.  See GPrint for example.
  1051.  
  1052.  
  1053.  
  1054.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1055.  
  1056.     Subroutine: LinePattern(pattern$)
  1057.     object files: fpattern.obj (drawline.obj)
  1058.  
  1059.        LinePattern passes a string of characters of up to 8 bytes to QLIB's
  1060.     DrawLine and DrawBox subroutines.  The pattern of bits in pattern$ modify
  1061.     lines so that they are drawn as a series of dots and/or dashes instead of
  1062.     as a solid line.  Lines drawn with a pattern will be slower than those
  1063.     drawn without a pattern.  In order to use pattern$, style% must be greater
  1064.     than zero. On monochrome screens, only style% 1 and 2 are useful.
  1065.     LinePattern must be called before each call to DrawLine or DrawBox if
  1066.     it is to work.
  1067.  
  1068.     Modes supported: All
  1069.  
  1070.      Style% parameters have the following effects:
  1071.  
  1072.           style% 1 = both foreground and background colors are
  1073.                   drawn, obliterating underlying pixels
  1074.           style% 2 = foreground only replaces pre-existing pixels.
  1075.           style% 3 = foreground is ORed with pre-existing pixels
  1076.           style% 4 = foreground is ANDed with pre-existing pixels.
  1077.  
  1078.     Example:
  1079.      pattern$ = SPACE$(8)
  1080.      CALL LinePattern(pattern$)
  1081.      CALL DrawBox(x0, y0, x1, y1, style%)
  1082.  
  1083.  
  1084.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1085.  
  1086.     Subroutine: LoadPCX(filename$)
  1087.     object files: loadpcx.obj (fload.obj, $plane.obj. $graph.obj)
  1088.  
  1089.        Reads and decodes .PCX-format file, copying to screen.
  1090.     LoadPCX assumes that the screen mode is appropriate for the image;
  1091.     for example, LoadPCX assumes that a 16-color .PCX image is loaded
  1092.     to a 16-color screen, or a 256-color .PCX image is loaded to a 256-
  1093.     color screen.  See also PCXInfo.  Returns with DOSError <> 0 if a
  1094.     file error occurred.
  1095.  
  1096.     Example:
  1097.  
  1098.     DEFINT A-Z
  1099.     DECLARE FUNCTION GetKey()
  1100.     TYPE pcxdata
  1101.          horiz AS INTEGER
  1102.          vert AS INTEGER
  1103.          colors AS INTEGER
  1104.          planes AS INTEGER
  1105.          xpixels AS INTEGER
  1106.          ypixels AS INTEGER
  1107.     END TYPE
  1108.  
  1109.     ' pcxdata.horiz is the horizontal resolution of the screen
  1110.     ' this is 640 for many EGA/VGA 16-color modes
  1111.  
  1112.     ' pcxdata.vert is the vertical resolution of the screen
  1113.     ' this is 350 for SCREEN 10 and 480 for SCREEN 12
  1114.  
  1115.     ' pcxdata.colors is the number of colors encoded in the .PCX file
  1116.     ' pcxdata.planes = 1 for SCREEN 1, 2 & 13, 4 for all 16-color modes
  1117.     ' pcxdata.xpixels is the number of horizontal pixels in the image
  1118.     ' pcxdata.ypixels is the number of vertical pixels in the image
  1119.  
  1120.     DIM a AS pcxdata
  1121.          p = VARPTR(a)
  1122.          name$ = "\pcx\demo.pcx"
  1123.          CALL PCXInfo(name$, p)
  1124.  
  1125.          b = &H12                           ; assume VGA 640 x 480
  1126.          IF a.ypixels <= 350 THEN b = &H10  ; use 640 x 350 if smaller image
  1127.          IF a.colors = 256 then b = &H13    ; SCREEN 13 if 256 colors
  1128.          CALL screenmode(b)
  1129.          CALL LoadPCX(name$)
  1130.          IF GetKey THEN CALL screenmode(3)
  1131.          END
  1132.  
  1133.  
  1134.  
  1135.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1136.  
  1137.     Subroutine: ScreenMode(mode%)
  1138.     object files: scrmode.obj (hgraph.obj, hmode.obj)
  1139.  
  1140.     ScreenMode allows graphics or text mode to be set, bypassing
  1141.     QuickBASIC's SCREEN command.  If your program uses QLIB's graphics
  1142.     subroutines instead of QuickBASIC's graphics commands, you can reduce
  1143.     your program's size significantly by using ScreenMode instead of
  1144.     SCREEN.  ScreenMode also allows you to use VESA mode &H6A, which
  1145.     is supported by QLIB's graphics (or use SVGA16 for high-resolution
  1146.     16-color modes).
  1147.  
  1148.     The mode% parameter is the BIOS mode number for the screen mode
  1149.     (except Hercules - QLIB uses the Microsoft convention of mode 8
  1150.     for Hercules since no BIOS mode number exists for Hercules).
  1151.  
  1152.     BIOS mode numbers and the equivalent QuickBASIC SCREEN numbers are:
  1153.  
  1154.          BIOS number      equipment             SCREEN number
  1155.  
  1156.            &H3            CGA, MCGA, EGA, VGA   SCREEN 0 (text mode)
  1157.            &H4            CGA, MCGA, EGA, VGA   SCREEN 1
  1158.            &H5            CGA, MCGA, EGA, VGA   SCREEN 1
  1159.            &H6            CGA, MCGA, EGA, VGA   SCREEN 2
  1160.            &H7            Monochrome, Hercules  SCREEN 0 (text mode)
  1161.                           EGA Monochrome
  1162.            &H8            Hercules, InColor     SCREEN 3
  1163.            &H40           ATT 6300              SCREEN 4
  1164.            &HD            EGA, VGA              SCREEN 7
  1165.            &HE            EGA, VGA              SCREEN 8
  1166.            &HF            EGA, VGA (monochrome) SCREEN 10   128k+ memory
  1167.            &H10           EGA, VGA              SCREEN 9    128k+ memory
  1168.            &H11           MCGA, VGA             SCREEN 11
  1169.            &H12           VGA                   SCREEN 12
  1170.            &H13           MCGA, VGA             SCREEN 13
  1171.            &H6A           VESA SVGA
  1172.  
  1173.     NOTE: ScreenMode is NOT intended for switching between a color
  1174.     monitor and a monochrome monitor.  Use ModeColor and ModeMono for
  1175.     monitor switching.   
  1176.  
  1177.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1178.  
  1179.      Subroutine: Palette16(attribute%, colorvalue%)
  1180.      object file: palet16.obj
  1181.  
  1182.      supports: EGA and VGA 16-color modes
  1183.  
  1184.           Palette16 changes the actual color associated with a particular
  1185.      color attribute.  If you call Palette16 with attribute% and
  1186.      colorvalue% both equal to -1, the default colors will be restored.
  1187.      Palette16 works in EGA and VGA 16-color modes, except where an EGA
  1188.      card is driving a CGA monitor.  See also Color16.
  1189.  
  1190.      Example:
  1191.           REM $INCLUDE: 'qlib.bi'
  1192.           REM  I want to use a color with low-intensity red
  1193.           REM  and high-intensity blue
  1194.           red% = 1: blue% = 3: green% = 0
  1195.           colorvalue% = Color16(red%, green%, blue%)
  1196.           REM  I'll use color attribute 8 for this color
  1197.           CALL Palette16(8, colorvalue%)
  1198.  
  1199.  
  1200.  
  1201.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1202.  
  1203.      Subroutine: Palette256(attribute%, colorvalue&)
  1204.      object file: palet256.obj
  1205.  
  1206.      supports: 256-color modes
  1207.  
  1208.           Similar to Palette16, Palette256 changes the actual color
  1209.      displayed by a specified color attribute.  Colorvalue& may be
  1210.      calculated from individual red, green and blue intensities using
  1211.      Color256.
  1212.  
  1213.      Example:
  1214.           REM $INCLUDE: 'qlib.bi'
  1215.  
  1216.           red% = 63               ' brightest red
  1217.           green% = 10             ' not much green
  1218.           blue% = 32              ' medium blue intensity
  1219.  
  1220.           colorvalue& = Color256(red%, green%, blue%)
  1221.           REM  I'll use color attribute 48 for this color
  1222.           CALL Palette256(48, colorvalue%)
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1228.  
  1229.     Subroutine: PCXInfo(filename$, dataptr%)
  1230.     object files: pcxinfo.obj ($graph.obj)
  1231.  
  1232.        Reads vital data from the header of a .PCX-format file.  From this
  1233.     data you may determine whether you can use the image or what screen
  1234.     mode will work best.  PCXInfo also updates the DOSError flag if an
  1235.     error occurred reading the file header.
  1236.  
  1237.  
  1238.     Example: see LoadPCX
  1239.  
  1240.  
  1241.  
  1242.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1243.  
  1244.     Subroutine: PutDot(x%, y%, style%)
  1245.       (formerly SetPixel)
  1246.     object files: putdot.obj ($graph.obj, $putdot.obj, $herc16,obj,
  1247.                               $ega16.obj, $vga256.obj)
  1248.  
  1249.     Modes supported: All
  1250.  
  1251.          Sets the pixel at (x%, y%) according to the specified style% and
  1252.     current GraphColor.  In monochrome modes, legal style% values are
  1253.     -1, 0, and 1.  Color modes may use style% -4 through 4.  Coordinates
  1254.     outside the active graphics viewport are ignored.
  1255.  
  1256.     Example:
  1257.          x% = 10: y% = 10: style% = 0
  1258.          CALL PutDot(x%, y%, style%)
  1259.          REM  In this example, the pixel will be turned off if it had been
  1260.          REM  on, and will be turned on if it had been off.
  1261.  
  1262.  
  1263.  
  1264.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1265.  
  1266.     Subroutine: Restore256(s%)
  1267.     object file: save256.obj (q$alloc.obj)
  1268.  
  1269.     supports: 256-color modes
  1270.  
  1271.          Restores palette registers saved by Save256.  See Save256, below.
  1272.  
  1273.  
  1274.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1275.  
  1276.     Function: s% = Save256
  1277.     object file: save256.obj (q$alloc.obj)
  1278.  
  1279.     supports: 256-color modes
  1280.  
  1281.          Saves all color palettes in a block of RAM, so you can restore
  1282.     the color registers at a later time with Restore256.  Save256 allocates
  1283.     a block of RAM large enough to save the registers, and returns the
  1284.     segment address of the block.  After you are done with the saved
  1285.     color registers, you may release the memory block with FreeMem(s%).
  1286.  
  1287.     Example:
  1288.          REM $INCLUDE: 'qlib.bi'
  1289.          SCREEN 13
  1290.          .
  1291.          .
  1292.          .
  1293.          REM  I've changed several of the color registers and I want to
  1294.          REM  save this particular set of colors
  1295.          s% = Save256
  1296.          IF s% = 0 THEN ...       'oops- not enough RAM available
  1297.          .
  1298.          .
  1299.          .
  1300.          REM  now I want to restore this set of colors
  1301.          CALL Restore256(S%)
  1302.  
  1303.  
  1304.         
  1305.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1306.  
  1307.     Subroutine: ScreenDump(oops%)
  1308.     object files: scrndump.obj (q$graph.obj)
  1309.  
  1310.     Modes supported: HGraph (mono) not yet tested with InColor
  1311.                      SCREEN 3
  1312.  
  1313.          Prints the active graphics screen on a graphics printer (Epson MX,
  1314.     FX, RX; IBM Graphics Printer, IBM ProPrinter, and compatibles).
  1315.     ScreenDump can be stopped with the ESC key.  If this occurs, oops% = 27
  1316.     is returned (27 is the ASCII character code for the ESC key).  If the
  1317.     computer is not in Hercules graphics mode, oops% = -1.  If all went
  1318.     well, oops% = 0.  Use PrinterReady (EQUIP.DOC) to see if the printer is
  1319.     ready.
  1320.  
  1321.     Example:
  1322.          CALL ScreenDump(oops%)
  1323.          oops$ = ""
  1324.          IF oops% = -1 THEN oops$ = "Not Hercules mode"
  1325.          IF oops% = 27 THEN oops$ = "Printing stopped"
  1326.          IF LEN(oops$) THEN PRINT oops$
  1327.  
  1328.  
  1329.  
  1330.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1331.  
  1332.     Subroutine: ShowGPage(gpage%, oops%)
  1333.     object files: gpage.obj ($graph.obj)
  1334.  
  1335.     Modes supported: HGraph (mono and InColor) pages 0 and 1
  1336.                      SCREEN 3      pages 0 and 1
  1337.                      SCREEN 7      pages 0 through 7  (depends on EGA memory)
  1338.                      SCREEN 8      pages 0 through 3  (depends on EGA memory)
  1339.                      SCREEN 9      pages 0 and 1      (256k EGA memory)
  1340.                      SCREEN 10     pages 0 and 1      (256k EGA memory)
  1341.                      VGA13X(0)     pages 0 through 3
  1342.                      VGA13X(1)     pages 0 through 2
  1343.                      VGA13X(2)     pages 0 and 1
  1344.  
  1345.          ShowGPage changes the graph page visible on the screen.
  1346.     This can be handy for animation or for storing one graph while another
  1347.     is displayed.  If gpage% is too large for the default mode, oops% = -1.
  1348.     See also GPage.
  1349.  
  1350.     Example:
  1351.          CALL HGraph              ' establish Hercules graphics mode
  1352.       CALL Use64k              ' allow 2 pages in graphics mode
  1353.               .
  1354.               .                   ' display graph 0
  1355.               .
  1356.          gpage% = 1
  1357.          CALL UseGPage(gpage%, oops%)
  1358.                                   ' now put a graph in the second page
  1359.               .
  1360.               .
  1361.               .
  1362.          CALL ShowGPage(gpage%, oops%)
  1363.                                   ' let's look at graph 1 now that it's 
  1364.               .                   ' complete
  1365.               .
  1366.               .
  1367.          gpage% = 0
  1368.          CALL GPage(gpage%, oops%) ' restore default output page
  1369.                                    ' and look at graph 0
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1375.  
  1376.     Subroutine: ShowGraphPlane(plane%, oops)
  1377.     object files: gplane.obj ($graph.obj)
  1378.  
  1379.     Modes supported: VESA6A, XMode16, SVGA16
  1380.                      SCREEN 7,8,12
  1381.                      SCREEN 9  (128k or more EGA memory)
  1382.                      SCREEN 10 (planes 0 and 2, 128k or more EGA memory)
  1383.  
  1384.         EGA and VGA memory in 16-color modes is arranged in 4 parallel
  1385.     "planes".  The 16 colors available when all planes are visible result
  1386.     from a combination of the data bits in each plane at each data address.
  1387.     The planes, numbered 0, 1, 2 and 3, each control a single color.  With
  1388.     the default palette, plane 0 is blue, plane 1 is green, plane 2 is red
  1389.     and plane 3 is "intensity".  A pixel that appears bright blue in the
  1390.     screen represents pixels at identical locations in the Blue and Intensity
  1391.     planes.  (Note that the actual colors each plane represents may change
  1392.     depending on the use of QuickBASIC's COLOR and PALETTE statements).
  1393.  
  1394.     The plane% parameters are:
  1395.  
  1396.     plane 0    plane% = 1
  1397.     plane 1    plane% = 2
  1398.     plane 2    plane% = 4
  1399.     plane 3    plane% = 8
  1400.  
  1401.     Use BASIC's OR operator to show more than one plane; i.e., to
  1402.     show only planes 0 and 3, plane% = 1 OR 8.  To restore normal output,
  1403.     plane% = 1 OR 2 OR 4 OR 8.
  1404.  
  1405.     Example:
  1406.         CALL ShowGraphPlane(plane%, oops)
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1412.  
  1413.     Subroutine: SetView(x0%, y0%, x1%, y1%)
  1414.     Subroutine: GetView(x0%, y0%, x1%, y1%)
  1415.     object files: view.obj ($graph.obj)
  1416.  
  1417.     Modes supported: All
  1418.  
  1419.          SetView establishes the active viewport on the active graphics
  1420.     page.  Most QLIB graphics subroutines limit their output to the
  1421.     active viewport.  GetView returns the viewport coordinates
  1422.     presently active.  QLIB's default viewport is the entire graphics
  1423.     screen.  If SetView is called with coordinates outside legal bounds
  1424.     (for example, if x1% = 1000), SetView limits the coordinates to the
  1425.     bounds for the active graphics mode (or to Hercules bounds if the
  1426.     system is either not in graphics mode or in an unsupported mode).
  1427.     This is NOT like QuickBASIC, which calls the out-of-bounds coordinate
  1428.     an illegal function call.  This SetView feature is handy for clearing
  1429.     out old view data or for establishing the entire screen as the
  1430.     viewport when the exact limits are variable or unknown (such as
  1431.     with XMode16).
  1432.  
  1433.     Example:
  1434.          CALL SetView(x0%, y0%, x1%, y1%)
  1435.  
  1436.  
  1437.  
  1438.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1439.  
  1440.     Subroutine: SmallText
  1441.     Subroutine: StdText
  1442.     object files: smalltxt.obj (gprint.obj, q$graph.obj, f8x8.obj)
  1443.  
  1444.     Modes supported: HGraph (mono and InColor)
  1445.                      VESA6A, XMode16, SVGA16, SVGA256
  1446.                      SCREEN 3,9,10,12
  1447.  
  1448.     GPrint and GLineEdit may be set to use a smaller 8 x 8 character,
  1449.     which allows up to 43 rows of text in Hercules graphics mode, where
  1450.     StdText (QLIB's default) results in a maximum 25 rows of text.  Once
  1451.     SmallText is called, GPrint and GLineEdit will print 8 x 8 text until
  1452.     the 8 x 14 character is restored with StdText.  8x8 and 8x14 text
  1453.     may be mixed on one screen.
  1454.  
  1455.     Example:
  1456.          CALL HGraph               ' establish Hercules graphics mode
  1457.          CALL SmallText            ' sets GPrint to use small text
  1458.          CALL GPrint(a$, x0%, y0%, style%)
  1459.  
  1460.  
  1461.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1462.  
  1463.     Subroutine: VGA13X(modenumber%)
  1464.     object files: vga13x.obj ($graph.obj)
  1465.  
  1466.     Requires VGA
  1467.  
  1468.          Provides extended VGA 256-color modes.  I have used these modes
  1469.     on PS/2 computers and with a variety of other VGA cards; it should be
  1470.     compatible with most VGA systems.  VGA13X modes provide up to twice the
  1471.     resolution of SCREEN 13, or up to 4 pages with resolution identical
  1472.     to SCREEN 13.
  1473.  
  1474.     VGA13X modes are:
  1475.  
  1476.                   horizontal pixels   vertical pixels     pages
  1477.  
  1478.     VGA13X(0)           320                200         0, 1, 2, 3
  1479.     VGA13X(1)           320                240           0, 1, 2
  1480.     VGA13X(2)           320                400             0, 1
  1481.     VGA13X(3)           360                480               0
  1482.  
  1483.     Example:
  1484.        CALL GetCRT(crt)
  1485.        IF crt = 3 THEN
  1486.            CALL VGA13X(2)         ' 2-page mode
  1487.            ELSE
  1488.            PRINT "VGA modes not available"
  1489.        END IF
  1490.           .
  1491.           .
  1492.           .
  1493.        REM  all done with graphics, go back to text mode
  1494.        CALL ModeColor               ' 80 x 25 text mode
  1495.        CALL XModeClear              ' clear QLIB's internal flags
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1501.  
  1502.     Function: goodmode% = SVGA16(i%)
  1503.     object file: svga16.obj ($svga.obj, $graph.obj, $banks.obj)
  1504.  
  1505.     SVGA16 sets most super VGA boards in either a 1024x768 16-color mode
  1506.     (i% = 1) or an 800x600 16-color mode (i% = 0).  Boards supported are:
  1507.  
  1508.     Ahead Technologies
  1509.     ATI
  1510.     Chips & Technologies
  1511.     Everex
  1512.     Genoa GVGA
  1513.     NCR
  1514.     Oak Technologies
  1515.     Paradise (Western Digital)
  1516.     Trident
  1517.     Trident 8900
  1518.     Tseng (Genoa, Orchid, Willow)
  1519.     Tseng 4000
  1520.     VESA standard
  1521.     Video 7
  1522.  
  1523.     SVGA16() returns goodmode = 0 if the requested mode is not available
  1524.     on your equipment, goodmode = -1 if successful.
  1525.  
  1526.     Most QLIB subroutines may be used with SVGA16 modes.  See documentation
  1527.     for each subroutine.
  1528.  
  1529.     QLIB's SVGA subroutines are derived from John Bridges' public domain
  1530.     VGAKIT board identification and bank switching code.
  1531.  
  1532.     Example:
  1533.        REM $INCLUDE: 'qlib.bi'       ' has function declaration for SVGA16()
  1534.  
  1535.        REM  Use SVGA mode if available, mode &H12 otherwise
  1536.        IF NOT SVGA16(1) THEN CALL ScreenMode(&H12)
  1537.  
  1538.  
  1539.  
  1540.  
  1541.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1542.  
  1543.     Function: goodmode% = SVGA256(i%)
  1544.     object file: svga256.obj ($svga.obj, $graph.obj, $banks.obj)
  1545.  
  1546.     SVGA256 is similar to SVGA16, but sets one of several 256-color modes.
  1547.     Modes available are:
  1548.  
  1549.     i% = 3:   1024x768
  1550.     i% = 2:    800x600
  1551.     i% = 1:    640x480
  1552.     i% = 0:    640x400
  1553.  
  1554.     Equipment supported is listed under SVGA16, plus:
  1555.  
  1556.     Compaq (640x480 only)
  1557.  
  1558.     !! DO NOT USE ANY I% VALUES OTHER THAN 0, 1, 2 & 3 !!
  1559.  
  1560.     SVGA256() returns goodmode = 0 if the requested mode is not available
  1561.     on your equipment, goodmode = -1 if successful.
  1562.  
  1563.     Most QLIB subroutines may be used with SVGA16 modes.  See documentation
  1564.     for each subroutine.
  1565.  
  1566.     QLIB's SVGA subroutines are derived from John Bridges' public domain
  1567.     VGAKIT board identification and bank switching code.
  1568.  
  1569.     Example:
  1570.        REM $INCLUDE: 'qlib.bi'       ' has function declaration for SVGA256()
  1571.  
  1572.        REM  Use SVGA mode if available, VGA13X mode otherwise
  1573.        IF NOT SVGA256(3) THEN CALL VGA13X(3)
  1574.  
  1575.  
  1576.  
  1577.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1578.  
  1579.     Subroutine: Use32k
  1580.     Subroutine: Use64k
  1581.     object file: q$herc.obj
  1582.  
  1583.     Requires Hercules (mono or InColor)
  1584.  
  1585.          Use32k masks the second 32k block of Hercules memory out of the
  1586.     memory map.  If the second 32k is included in the memory map, QLIB's
  1587.     video routines can use all Hercules screen pages.  The second 32k of
  1588.     Hercules video memory conflicts with most color monitors' address space,
  1589.     so Use32k should be used to mask the second 32k out of the memory map
  1590.     for two-monitor systems.  Use64k allows the second block.  QLIB's
  1591.     default is Use32k.   You MUST call Use64k if you want to use graphics
  1592.     page 1 with Hercules systems.
  1593.  
  1594.     Example:
  1595.          CALL GetCRT(crt%)
  1596.          IF crt% >= 128 THEN CALL Use64k
  1597.  
  1598.  
  1599.  
  1600.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1601.  
  1602.     Subroutine: UseFont (fseg%, fptr%, points%, bytes%)
  1603.     object files: usefont.obj, f8x14.obj
  1604.  
  1605.     Supports: all graphics modes with ymax% > 200
  1606.  
  1607.     UseFont permits use of non-standard fonts with GPrint, GPrintX, GCenter
  1608.     and GCenterX.  The font you wish to use must be somewhere in memory,
  1609.     either "hardwired" into your program or loaded from a disk file.
  1610.  
  1611.     Parameters used when calling UseFont are:
  1612.  
  1613.     fseg% = segment address of character definition data
  1614.     fptr% = offset address of character definition data
  1615.     points% = height of each character on screen (in pixel rows)
  1616.     bytes% = byte interval from the start of one character definition
  1617.              to the next
  1618.  
  1619.     QLIB's GPrint subroutines assume that each character in the font is
  1620.     8 pixels wide.
  1621.     To use character widths other than 8 pixels, use FontWidth.
  1622.     This can be used not only to print properly spaced characters in a
  1623.     font less than 8 bits wide, but may also be used to add extra space
  1624.     between characters in a string.  Note that the character definition
  1625.     data still needs to be 8 bits wide; FontWith's pixel width parameter
  1626.     tells GPRINT how much space to leave between characters.
  1627.  
  1628.     Example:
  1629.       REM $INCLUDE: 'C:\QB4\QLIB.BI'
  1630.       REM   I want to use the italic font supplied by Hercules with the
  1631.       REM   InColor Card and Graphics Card Plus.  All Hercules font files
  1632.       REM   have a byte interval of 16, even for those fonts which are
  1633.       REM   less than 16 points high.
  1634.  
  1635.       filename$ = "C:\RAMFONT\ITALICS.FNT"
  1636.       fseg% = FLoad (filename$)       ' load font file into far memory
  1637.       fptr% = 0                       ' Hercules font definitions begin
  1638.                                       ' at the start of the file
  1639.       points% = 14: bytes% = 16       ' 14-point font
  1640.       CALL UseFont (fseg%, fptr%, points%, bytes%)
  1641.       CALL FontWidth(10)              ' add extra space
  1642.  
  1643.       REM  GPrint will now use italics font until SmallText or StdText is
  1644.       REM  is called, or until UseFont is called with another font definition
  1645.       REM  Once you are done with the font, release the far memory with
  1646.       REM  CALL  FreeMem (fseg%)
  1647.  
  1648.  
  1649.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1650.  
  1651.     Subroutine: UseHercules
  1652.     Subroutine: UseDefault
  1653.     object file: q$graph.obj
  1654.  
  1655.       UseHercules forces QLIB's graphics subroutines to use Hercules-
  1656.     mode algorithms.  This is handy when you want to create a virtual
  1657.     graphics screen (for ScreenDump, as an example) while the computer
  1658.     is displaying a graph in another graphics mode.  UseDefault causes
  1659.     QLIB to use the algorithms for the system's active graphics mode.
  1660.     UseHercules is NOT required if the system is in Hercules mode.
  1661.  
  1662.     Example:
  1663.       CALL UseHercules
  1664.           .
  1665.           .
  1666.           .
  1667.       CALL UseDefault
  1668.  
  1669.  
  1670.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1671.  
  1672.     Subroutine: UseGPage(gpage%, oops%)
  1673.     object files: gpage.obj ($graph.obj)
  1674.  
  1675.     Modes supported: HGraph (mono and InColor)    pages 0 and 1
  1676.                      SCREEN 3         pages 0 and 1
  1677.                      SCREEN 7         pages 0 through 7  (with 265k EGA)
  1678.                      SCREEN 8         pages 0 through 3  (with 265k EGA)
  1679.                      SCREEN 9         pages 0 and 1      (256k EGA memory)
  1680.                      SCREEN 10        pages 0 and 1      (256k EGA memory)
  1681.                      VGA13X(0)        pages 0 through 3
  1682.                      VGA13X(1)        pages 0 through 2
  1683.                      VGA13X(2)        pages 0 and 1
  1684.  
  1685.          UseGPage changes the default screen page for QLIB's graphics
  1686.     subroutines.  QLIB's default gpage% is 0.  If multiple pages are not
  1687.     available for the current mode, or gpage% is too big, oops% = -1.
  1688.  
  1689.     Example:
  1690.          CALL HGraph              ' establish Hercules graphics mode
  1691.                                   ' HGraph calls Use64k
  1692.          gpage% = 1
  1693.          CALL UseGPage(gpage%, oops%)
  1694.                                   ' QLIB's graphics subroutines use page 1 now
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1700.  
  1701.     Subroutine: XMode16(m%, maxX%, maxY%)
  1702.     Subroutine: XMode16A(m0%, m1%, maxX%, maxY%)
  1703.     object file: xmode.obj ($graph.obj)
  1704.  
  1705.     Subroutine: XModeClear
  1706.     Subroutine: ModeColor
  1707.  
  1708.        XMode16 subroutines allow the use of many extended EGA and VGA
  1709.     graphics cards at higher resolutions than IBM's products allow, in
  1710.     16-color modes.  Depending on the graphics card/monitor combination
  1711.     in use, resolutions up to 800 pixels horizontal and 600 pixels vertical
  1712.     are possible.  The manual supplied with your extended EGA or VGA card
  1713.     contains the information you need to put the high-resolution modes to
  1714.     work.  A multi-frequency monitor is generally required (see the graphics
  1715.     card manual for specific requirements).
  1716.  
  1717.     You must have the required equipment and use the correct mode number;
  1718.     hardware damage may result from improper use of XMode16.  I cannot be
  1719.     held responsible for damage resulting from use of XMode16.
  1720.  
  1721.     When using XMode16, the parameters required are:
  1722.  
  1723.      m% = mode number (from graphics card manual, for 8086 register AL)
  1724.      maxX% = maximum horizontal dimension
  1725.      maxY% = maximum vertical dimension
  1726.  
  1727.     If 800 horizontal pixels are available, maxX% should be 799.  Similarly,
  1728.     if 600 vertical pixels are possible, maxY% should be 599.
  1729.  
  1730.     If your graphics card requires two mode parameters in the 8086's
  1731.     AL and BL registers, use XMode16A instead, where
  1732.  
  1733.      m0% = mode number for AL register
  1734.      m1% = mode number for BL register
  1735.      maxX% = maximum horizontal dimension
  1736.      maxY% = maximum vertical dimension
  1737.  
  1738.     Any QLIB subroutines compatible with XMode16 will work equally well
  1739.     with XMode16A.
  1740.  
  1741.     Your graphics card manual lists mode numbers, equipment requirements,
  1742.     and the number of horizontal and vertical pixels corresponding to the
  1743.     mode.  Mode numbers are usually in hex format.  Some modes and
  1744.     corresponding mode numbers are listed on the next page:
  1745.  
  1746.  
  1747.  
  1748.     Equipment            mode     mode number   Example
  1749.  
  1750.     Orchid ProDesigner   800x600     &H29       CALL XMode16(&H29, 799%, 599%)
  1751.     STB EM/16
  1752.     Genoa
  1753.     Sigma X16
  1754.  
  1755.  
  1756.     Everex MED EGA       640X480     &H70, &H00
  1757.     (Micro Enhancer Deluxe)                CALL XMode16a(&H70, &H00, 639%, 479%)
  1758.                          752x410     &H70, &H01
  1759.                                            CALL XMode16a(&H70, &H01, 751%, 409%)
  1760.  
  1761.  
  1762.     ATI VGA Wonder       800x600     &H54       CALL XMode16(&H54, 799%, 599%)
  1763.  
  1764.  
  1765.     ATI VIP              800x560     &H53       CALL XMode16(&H53, 799%, 559%)
  1766.  
  1767.  
  1768.     Paradise Plus-16     800x600     &H58       CALL XMode16(&H58, 799%, 599%)
  1769.     Paradise Professional
  1770.  
  1771.     Video 7 Fastwrite    800x600     &H62       CALL XMode16(&H62, 799%, 599%)
  1772.     Video 7 VRAM
  1773.  
  1774.     If any of this information conflicts with the specifications in your
  1775.     video card's instruction manual, the manual's recommendation is a safer
  1776.     bet.  Note that all the above modes require a multi-frequency monitor.
  1777.  
  1778.     When you're all done with Graphics mode, CALL ModeColor to return to
  1779.     80x25 text mode, and CALL XModeClear to reset QLIB's internal XMode flags.
  1780.  
  1781.  
  1782.      REM  All done with graphics for now, go back to 80 x 25 text mode
  1783.      CALL ModeColor
  1784.      REM  also clear QLIB's internal flags
  1785.      CALL XModeClear
  1786.  
  1787.   ***************** QWINDOW USER-DEFINED COORDINATE SUBSYSTEM ****************
  1788.  
  1789.  
  1790.   The QLIB QWindow user-defined coordinate subsystem for QLIB graphics is
  1791.   intended as a replacement for BASIC's WINDOW command.  The QWindow system
  1792.   permits the programmer to specify custom coordinates for any QLIB graphics
  1793.   mode, and changes the direction of increasing y-coordinates from the
  1794.   default top-to-bottom to the more familiar bottom-to-top orientation.
  1795.  
  1796.   QWindow subroutines are listed at the end of this file.
  1797.  
  1798.   For each QWindow graphics subroutine, the usage and calling parameters are
  1799.   identical to the primary QLIB graphics subroutine.  For example,
  1800.   to use QWBitBlockBytes, see the documentation for BitBlockBytes, but
  1801.   call QWBitBlockBytes with QWindow coordinates.
  1802.  
  1803.   If you have defined your own coordinates, you may still use QLIB's primary
  1804.   graphics subroutines with the absolute coordinates at the beginning of
  1805.   this file.  If your program repeatedly calls QLIB graphics subroutines
  1806.   with the same coordinates, your program will run a bit faster if you
  1807.   convert QWindow coordinates to QLIB's native absolute coordinates and
  1808.   use the non-QWindow subroutine.  See QW2Abs.
  1809.  
  1810.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1811.  
  1812.     Subroutine: QW2Abs(x%, y%)
  1813.     object file: qw2abs.obj, qwindow.obj
  1814.  
  1815.         QW2Abs converts QWindow coordinates to QLIB's native absolute
  1816.     coordinates.  This is handy if you will be repeatedly calling QLIB
  1817.     graphics subroutines with the same coordinates; convertng to absolute
  1818.     coordinates and calling the non-QWindow subroutine will make your
  1819.     program run a bit faster.
  1820.  
  1821.  
  1822.    
  1823.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1824.  
  1825.     Subroutine: QWindow(x0%, y0%, x1%, y1%)
  1826.     object file: qwindow.obj ($graph.obj)
  1827.  
  1828.         QWindow establishes the user-defined coordinate system.  The
  1829.     coordinate at (x0%, y0%) is the lower left corner of the working area
  1830.     and the coordinate at (x1, y1) is the upper right corner of the area.
  1831.     The working area can be either the entire screen or QLIB's active view
  1832.     area (see QWScreen and QWView).  If x0% is less than 0, the origin
  1833.     of the horizontal axis will be shifted right.  If y0% is less than 0,
  1834.     the origin of the vertical axis will be shifted up.  Maximum values
  1835.     for all coordinates is 32,767; minimum is -32,768.
  1836.     
  1837.  
  1838.     Example:
  1839.        DEFINT A-Z
  1840.        REM  my data series has a minimum y-value of -32 and a maximum
  1841.        REM  y-value of 181, while the x-values range from -10 to 75
  1842.  
  1843.        CALL ScreenMode(&H10)                ' EGA 640x350 mode
  1844.        CALL QWScreen                        ' coordinates relative
  1845.                                             ' to entire screen
  1846.        CALL QWindow(-10, -32, 75, 181)      ' user-defined graph coordinates
  1847.        CALL QWLine(0, -32, 0, 181, 1)       ' draw vertical axis
  1848.        CALL QWLine(-10, 0, 75, 0,  1)       ' draw horizontal axis
  1849.  
  1850.        REM put dots on the screen for a X vs. Y chart
  1851.        FOR i = 0 to 100
  1852.            CALL QWPutDot(x%(i), y%(i), style%)
  1853.        NEXT i
  1854.  
  1855.  
  1856.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1857.  
  1858.     Subroutine: QWScreen
  1859.     Subroutine: QWView
  1860.     object file: qwindow.obj ($graph.obj)
  1861.  
  1862.        These subroutines allow you to define your coordinate system
  1863.     relative to the entire screen (QWScreen) or relative to QLIB's active
  1864.     View area.
  1865.  
  1866.     Example:
  1867.        DEFINT A-Z
  1868.        REM  I want to use 90% of the screen dimensions for a plot with
  1869.        REM  coordinates from -100 to +100
  1870.  
  1871.        REM  start with View equal to entire screen area
  1872.        CALL ResetView
  1873.  
  1874.        REM  next, define the coordinate system, relative to entire screen
  1875.        CALL QWindow(-100, -100, 100, 100)
  1876.        CALL QWScreen
  1877.  
  1878.        REM  now get the absolute coordinates for 90% of the screen dimensions
  1879.        x0% = -90: y0% = -90
  1880.        x1% = 90: y0% = 90
  1881.        CALL QW2Abs(x0%, y0%)       ' convert first coordinate
  1882.        CALL QW2Abs(x1%, y1%)       ' convert second coordinate
  1883.  
  1884.        REM  use absolute coordinates to set QLIB view area
  1885.        CALL SetView(x0%, y0%, x1%, y1%)
  1886.  
  1887.        REM  make QWindow coordinates relative to active view area
  1888.        CALL QWView
  1889.  
  1890.        REM  ready to go!
  1891.  
  1892.  
  1893.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1894.  
  1895.     QWindow subroutines, the comparable QLIB subroutine and QWindow
  1896.     object files are listed below:
  1897.  
  1898.     QWindow subroutine   QLIB subroutine      object file
  1899.  
  1900.     QWLine               DrawLine             qwline.obj
  1901.     QWBox                DrawBox              qwline.obj
  1902.     QWFillBox            FillBox              qwline.obj
  1903.     QWFill               FillArea             qwfill.obj
  1904.     QWGCenter            GCenter              qwcenter.obj
  1905.     QWGCenterX           GCenterX             qwcentrx.obj
  1906.     QWCircle             DrawCircle           qwcircle.obj
  1907.     QWGLineEdit          GLineEdit            qwgedit.obj
  1908.     QWGPrint             GPrint               qwgprint.obj
  1909.     QWGPrintUP           GPrintUP             qwgprint.obj
  1910.     QWGPrintDOWN         GPrintDOWN           qwgprint.obj
  1911.     QWBitBlockBytes      BitBlockBytes        qwblock.obj
  1912.     QWBitBlockSave       BitBlockSave         qwblock.obj
  1913.     QWBitBlockRestore    BitBlockRestore      qwblock.obj
  1914.     QWBitPlaneBytes      BitPlaneBytes        qwplane.obj
  1915.     QWBitPlaneSave       BitPlaneSave         qwplane.obj
  1916.     QWBitPlaneRestore    BitPlaneRestore      qwplane.obj
  1917.     QWGetDot             GetDot               qwgetdot.obj
  1918.     QWPutDot             PutDot               qwputdot.obj
  1919.     QWGPrintX            GPrintX              qwprintx.obj
  1920.     QWGPrint2X           GPrint2X             qwprintx.obj
  1921.     QWGPrintUPX          GPrintUPX            qwprintx.obj
  1922.     QWGPrintDOWNX        GPrintDOWNX          qwprintx.obj
  1923.     QWGPrintUP2X         GPrintUP2X           qwprintx.obj
  1924.     QWGPrintDOWN2X       GPrintDOWN2X         qwprintx.obj
  1925.     QWGCursor            GCursor              qwcursor.obj
  1926.     QWGUCursor           GUCursor             qwcursor.obj
  1927.  
  1928.     In all cases, QWindow subroutines are called from your BASIC program
  1929.     with the same parameters, except that screen coordinates are QWindow
  1930.     coordinates instead of QLIB's native absolute pixel locations.
  1931.  
  1932.