home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / progmisc / asmlib.zip / GRAPHICS.DOC < prev    next >
Text File  |  1992-06-08  |  56KB  |  1,586 lines
  1.  
  2. ****************************** GRAPHICS *************************************
  3.  
  4. ASMLIB Graphics (C) Copyright 1991, 1992 Douglas Herr
  5. All rights reserved
  6.  
  7. ASMLIB recognizes and automatically supports several graphics modes,
  8. including several which are not recognized by IBM's BIOS.  You should
  9. assume that all ASMLIB graphics subroutines write directly to the video
  10. hardware.  IMPORTANT: ALL ASMLIB GRAPHICS SUBROUTINES ASSUME DS:@DATA.
  11.  
  12. Locations on Graphics screens are defined by coordinate pairs such as (x,y).
  13. X-coordinates are the horizontal dimensions of the screen, and Y-coordinates
  14. are the vertical coordinates.  X = 0 is the at the left edge of the screen,
  15. and X = 719 is the right edge of a Hercules screen, while Y = 0 is the top
  16. edge of the screen and Y = 347 is the bottom (Hercules).  Thus, the
  17. coordinate specified by (719,0) is the extreme upper right corner of a
  18. Hercules screen.
  19.  
  20. Graphics subroutines as powerful and flexible as ASMLIB's can be quite
  21. large.  If you have licenced ASMLIB source code, you can use several
  22. pre-defined conditional assembly directives to eliminate code from
  23. ASMLIB object files if you do not want or need to support all graphics
  24. modes:
  25.  
  26.         NOHERC      eliminates all Hercules and InColor code
  27.         NOINCOLOR   eliminates code for the InColor card
  28.                (InColor works with Hercules monochrome code in 2 colors)
  29.         NO256       eliminates code for the three 256-color modes
  30.         NOCGA       eliminates code for CGA graphics modes
  31.         NOMCGA      elimiates code for MCGA mode 11h
  32.         NOLPATTERN  elimiates code for non-solid lines (in DRAWLINE.ASM)
  33.  
  34. for example, if you want line drawing programs to use only EGA/VGA-type
  35. 16-color modes, assemble DRAWLINE.ASM like this:
  36.  
  37.          C:\MASM\>masm /dnoherc /dnocga /dnovga256 /dnomcga drawline;
  38.  
  39. this reduces the size of drawline.obj significantly and speeds its
  40. operation somewhat.
  41.  
  42. BitBlock subroutines in ASMHUGE.LIB work with huge data blocks (larger
  43. than 64k).  This permits entire EGA, VGA or InColor screens to be saved
  44. in one block if sufficient RAM is available.
  45.  
  46.  
  47. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  48.  
  49. Graphics modes and pages supported are:
  50.  
  51. Mode           Maximum x   Maximum y   Colors  Pages (1)  Equipment
  52.                 ("xmax")    ("ymax")
  53.  
  54. HGraph           719          347       2         0, 1    HGC, HGC+ (2)
  55. HGraph           719          347      16         0, 1    InColor  (2)
  56. 04h, 05h         319          199       4         0       CGA, EGA, MCGA, VGA
  57. 06h              639          199       2         0       CGA, EGA, MCGA, VGA
  58. 0Dh              319          199       16        0 - 7   EGA, VGA  (3)
  59. 0Eh              639          199       16        0 - 3   EGA, VGA  (3)
  60. 0Fh              639          349       4         0       EGA, VGA  (4)
  61. 10h              639          349       16        0, 1    EGA, VGA  (3,5)
  62. 11h              639          479       2         0       MCGA, VGA
  63. 12h              639          479       16        0       VGA
  64. 13h              319          199       256       0       MCGA, VGA
  65. 40h              639          399       2         0       ATT 6300 (6)
  66. 6Ah              799          599       16        0       VESA  (7)
  67. XMode16      up to 799     up to 599    16        0       Super EGA/VGA
  68. Super13          319          399       256       0, 1    VGA
  69. Super13a         359          479       256       0       VGA
  70. SVGA16      799 or 1023   599 or 767    16        0       Super VGA (8)
  71. SVGA256     639 to 1023   399 to 767    256       0       Super VGA (8)
  72.  
  73. (1) page numbering begins with page 0.  Several modes have sufficient
  74.     memory available for additional page(s).
  75. (2) page 1 available after calling Use64k
  76. (3) EGA pages assumes 256k EGA memory
  77. (4) monochrome monitor only
  78. (5) EGA with 128k or more memory
  79. (6) I have not tested this yet.  Feedback please!
  80. (7) VESA6A is supported by many Super VGA cards with multi-frequency
  81.     monitors
  82. (8) requires VGAKIT-compatible Super VGA and multi-frequency monitor.  See
  83.     WhichVGA in SYSTEM.DOC and SVGA16 and SVGA256 in MODE.DOC.
  84.  
  85. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  86.  
  87. BITBLOCKBYTES: calculate bytes required to save a bit block
  88. Source:        bbbytes.asm ($graph.asm)
  89.  
  90. Call with:     DS:[BX] pointing to x- and y-coordinate data (see example)
  91. Returns:       DX:AX = bytes required to save the bit block
  92.                small or medium model:
  93.                   if CF = 0, bytes required is less than 64k segment
  94.                      => no problem
  95.                   if CF = 1, bit block is too big for a 64k segment
  96.                      small or medium model BitBlock subroutines will
  97.                      not work properly
  98. Uses:          AX, DX, flags
  99. Supports:      all ASMLIB graphics modes; call BitBlockBytes while
  100.                the system is in the mode you intend to use.  Otherwise,
  101.                an incorrect byte size may be returned, leading to either
  102.                wasted memory or memory allocation errors.
  103. Example:
  104.  
  105. include asm.inc
  106.  
  107. extrn   bitblockbytes:proc
  108.  
  109. .data
  110. x0      dw 100,43         ; first corner at (100,43)
  111. x1      dw 175,143        ; second corner at (175,143)
  112.  
  113. .code
  114. ; program fragment assumes DS:@data
  115.         .
  116.         .
  117.         .
  118.         lea    bx,x0          ; DS:[BX] points to bit block corner data
  119.         call   bitblockbytes  ; returns AX = byte size of buffer required
  120.         jc     too_big        ; bit block is too big if CF = 1 (small or med)
  121.  
  122. ; note that when the huge model is used, memory greater than 64k must be
  123. ; allocated with DOS function 48h.  See STARTUP.ASM to release unused
  124. ; memory to allow DOS memory allocation.
  125.  
  126.  
  127. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  128.  
  129. BITPLANEBYTES: calculate bytes to save one plane of a bit block
  130.                alternate entry to BitBlockBytes; calculates bytes
  131.                required to save one plane of multi-plane modes
  132. Source:        bbbytes.asm ($graph.asm)
  133. Call with:     DS:[BX] pointing to x- and y-coordinate data
  134. Returns:       DX:AX = bytes required to save the bit plane
  135.                small or medium model:
  136.                   if CF = 0, bytes required is less than 64k
  137.                      => no problem
  138.                   if CF = 1, bit plane is too big for a 64k segment
  139.                      small or medium model BitPlane subroutines will
  140.                      not work properly
  141. Uses:          AX, DX, flags
  142. Supports:      all ASMLIB graphics modes; call BitPlaneBytes while
  143.                the system is in the mode you intend to use.  If the
  144.                system is is not in a multi-plane mode, BitPlaneBytes
  145.                will give you the same results as BitBlockBytes.
  146.                Graphics modes with multiple planes are mode 0Fh (2 planes)
  147.                and all 16-color modes (4 planes).
  148. Example:
  149.  
  150. include asm.inc
  151.  
  152. extrn   bitplanebytes:proc
  153.  
  154. .data
  155. x0      dw 100,43         ; first corner at (100,43)
  156. x1      dw 175,143        ; second corner at (175,143)
  157.  
  158. .code
  159. ; program fragment assumes DS:@data
  160.         .
  161.         .
  162.         .
  163.         lea    bx,x0          ; DS:[BX] points to bit block corner data
  164.         call   bitplanebytes  ; returns AX = byte size of buffer required
  165.         jc     too_big        ; unlikely
  166.  
  167.  
  168. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  169.  
  170. CIRCLEASPECT:  modifies aspect ratio of circle
  171. Source:        drawcirc.asm ($graph.asm)
  172.  
  173. Call with:     AH = numerator of aspect ratio
  174.                AL = denominator of aspect ratio
  175.                AH <> 0, AL <> 0
  176.  
  177.                CircleAspect is used with DrawCircle to draw an ellipse.
  178.                An aspect ratio less than one makes a flat ellipse and an
  179.                aspect ratio greater than one makes a tall ellipse.
  180.                Aspect ratios greater than 5 or less than 1/5 may cause
  181.                unpredictable results.
  182.  
  183. Returns:       nothing
  184. Uses:          nothing; all registers and flags are saved
  185. Supports:      all ASMLIB graphics modes
  186. Example:       see DrawCircle
  187.  
  188.  
  189.  
  190. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  191.  
  192. DEFGMODE:      restore ASMLIB's internal flags to use system graphics
  193.                mode (see ForceGMode)
  194. Source:        defgmode.asm
  195.  
  196. Call with:     no parameters
  197. Returns:       nothing
  198. Uses:          nothing
  199. Supports:      all ASMLIB graphics modes
  200. Example:       see ForceGMode
  201.  
  202.  
  203.  
  204. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  205.  
  206. DRAWCIRCLE:    draw a circle
  207. Source:        drawcirc.asm ($graph.asm, $putdot.asm)
  208.  
  209. Call with:     DS:[BX] pointing to circle center coordinates and x-radius
  210.                Drawmodes supported are:
  211.                 4 = AND the foreground color with the screen
  212.                 3 = OR the foreground color with the screen
  213.                 1, 2 = use foreground color
  214.                 0 = XOR circle with existing screen
  215.                -1, -2 = use background color
  216.                -3 = OR the background color with the screen
  217.                -4 = AND the background color with the screen
  218.                See DrawMode for more information
  219.                See also CircleAspect
  220. Returns:       nothing
  221. Uses:          nothing
  222. Supports:      all ASMLIB graphics modes
  223. Example:
  224.  
  225. include asm.inc
  226. extrn   drawcircle:proc, circleaspect:proc
  227.  
  228. .data
  229. xcenter dw 100              ; DrawCircle data must be words
  230. ycenter dw 100              ; the circle is centered at (100,100)
  231. xradius dw 50               ; x-dimension radius in pixels (>0)
  232.  
  233. .code
  234. ; program fragment assumes DS:@data
  235.         .
  236.         .
  237.         .
  238.         mov   ah,5
  239.         mov   al,1          ; a tall ellipse
  240.         call  circleaspect
  241.  
  242.         lea   bx,xcenter    ; DS:[BX] points to circle data
  243.         call  drawcircle    ; draw the circle
  244.  
  245.  
  246. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  247.  
  248. DRAWBOX:       draw a rectangle on a graphics screen
  249. Source:        drawbox.asm ($graph.asm, $vert.asm, $horiz.asm, several others)
  250.  
  251. Call with:     DS:[BX] pointing to box corner data
  252.                Drawmodes supported are:
  253.                 4 = AND the foreground color with the screen; color modes
  254.                 3 = OR the foreground color with the screen
  255.                 1, 2 = use foreground color: all modes
  256.                 0 = XOR foreground color with existing pixels
  257.                -1, -2 = use background color: all modes
  258.                -3 = OR the background color with the screen
  259.                -4 = AND the background color with the screen; color modes
  260.                See DrawMode for more information; see also LinePattern
  261. Returns:       nothing
  262. Uses:          nothing
  263. Supports:      all ASMLIB graphics modes
  264. Example:
  265.  
  266. include asm.inc
  267.  
  268. extrn   drawbox:proc
  269.  
  270. .data
  271. x0      dw 25,10            ; first corner at (25,10); data is word size
  272. x1      dw 301,97           ; opposite corner at (301,97)
  273.  
  274. .code
  275. ; program fragment assumes DS:@data
  276.         .
  277.         .
  278.         lea   bx,x0         ; DS:[BX] points to box corner data
  279.         call  drawbox
  280.  
  281.  
  282. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  283.  
  284. DRAWLINE:      draw a line on a graphics screen
  285. Source:        drawline.asm ($graph.asm, $vert.asm, $horiz.asm,
  286.                              $loslope.asm, $hislope.asm, many others)
  287.  
  288. Call with:     DS:[BX] pointing to line endpoint data
  289.                Drawmodes supported are:
  290.                 4 = AND the foreground color with the screen; color modes
  291.                 3 = OR the foreground color with the screen
  292.                 1, 2 = use foreground color: all modes
  293.                 0 = XOR foreground color with existing pixels
  294.                -1, -2 = use background color: all modes
  295.                -3 = OR the background color with the screen
  296.                -4 = AND the background color with the screen; color modes
  297.                See DrawMode for more information; see also LinePattern
  298. Returns:       nothing
  299. Uses:          nothing
  300. Supports:      all ASMLIB graphics modes
  301. Example:
  302.  
  303. include asm.inc
  304.  
  305. extrn   drawline:proc
  306.  
  307. .data
  308. x0      dw 25,10            ; first endpoint at (25,10); data is word size
  309. x1      dw 301,97           ; other end of line at (301,97)
  310.  
  311. .code
  312. ; program fragment assumes DS:@data
  313.         .
  314.         .
  315.         lea   bx,x0         ; DS:[BX] points to line coordinate data
  316.         call  drawline
  317.  
  318.  
  319. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  320.  
  321. DRAWMODE:      control ASMLIB graphics drawing mode
  322. Source:        $graph.asm
  323.  
  324.                DrawMode is a public byte in DGROUP used to control the
  325.                operation of many ASMLIB subroutines.  ASMLIB's default
  326.                drawmode is 1.
  327.  
  328.                Typically, drawmodes have the following effects:
  329.                 2 = use foreground color only; text is printed without
  330.                     background, foreground only of line patterns or
  331.                     fill patterns is used
  332.                 1 = use foreground and background; text is printed with
  333.                     background, line patterns and fill patterns update
  334.                     both foreground and background
  335.                 0 = foreground color is XORed with the existing screen
  336.                     (not supported in 256-color or CGA 4-color modes)
  337.                -1 = characters or fill pattern drawn with foreground
  338.                     and background reversed
  339.                -2 = character or line drawn with background color only
  340.  
  341. Supports:      all ASMLIB graphics modes
  342. Example:
  343.  
  344. include asm.inc
  345.  
  346. .data
  347. extrn   drawmode:byte
  348.  
  349. .code
  350. ; program fragment assumes DS:@data
  351.         .
  352.         .
  353.         mov     drawmode,2      ; print text with foreground color only
  354.  
  355.  
  356. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  357.  
  358. FILLAREA:      fills an irregular area on a graphics screen
  359. Source:        fillarea.asm ($graph.asm, $horiz.asm, $getdot.asm,
  360.                              several others)
  361.  
  362. Call with:     DS:[BX] pointing to seed pixel coordinates
  363.  
  364.                Fills many irregularly-shaped areas with color and/or
  365.                pattern, beginning at (x,y).  FillArea may not work
  366.                properly with regions which have concave boundaries
  367.                crossing horizontal lines.  The area's boundary is
  368.                defined by a solid line of non-zero pixels.
  369.                DrawModes supported are:
  370.                 2 = fill with foreground color only (if fill pattern
  371.                     has been defined): 16-color modes
  372.                 1 = fill with foreground (and background, if fillpattern
  373.                     defined): all modes
  374.                See also FillPattern.
  375. Returns:       nothing
  376. Uses:          nothing
  377. Supports:      all ASMLIB graphics modes
  378. Example:
  379.  
  380. include asm.inc
  381.  
  382. extrn   fillarea:proc
  383.  
  384. .data
  385. x       dw 10,15         ; start fill operation at x=10, y=15
  386.  
  387. .code
  388. ; program fragment assumes DS:@data
  389.         .
  390.         .
  391.         lea    bx,x
  392.         call   fillpattern
  393.  
  394.  
  395. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  396.  
  397. FILLBOX:       draw a filled rectangle on a graphics screen
  398. Source:        fillbox.asm ($graph.asm, $horiz.asm, several others)
  399.  
  400. Call with:     DS:[BX] pointing to box corner data
  401.                Drawmodes supported are:
  402.                 4 = AND the box with the pre-existing screen
  403.                 3 = OR the foreground color with the screen
  404.                 1, 2 = use foreground color
  405.                 0 = XOR foreground color with existing pixels
  406.                -1, -2 = use background color
  407.                -3 = OR the background color with the screen
  408.                -4 = AND the background color with pre-existing screen
  409.                See DrawMode for more information; also see FillPattern.
  410. Returns:       nothing
  411. Uses:          nothing
  412. Supports:      all ASMLIB graphics modes
  413. Example:
  414.  
  415. include asm.inc
  416.  
  417. extrn   fillbox:proc
  418.  
  419. .data
  420. x0      dw 25,10            ; first corner at (25,10); data is word size
  421. x1      dw 301,97           ; opposite corner at (301,97)
  422.  
  423. .code
  424. ; program fragment assumes DS:@data
  425.         .
  426.         .
  427.         lea   bx,x0         ; DS:[BX] points to box corner data
  428.         call  fillbox
  429.  
  430.  
  431. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  432.  
  433. FILLPATTERN:   define an optional pattern for FillArea & FillBox
  434. Source:        fpattern.asm
  435.  
  436. Call with:     DS:[BX] pointing to ASCIIZ pattern string.
  437.                Up to 8 characters in the string will be used.
  438.                The pattern must be re-defined before each call to a line
  439.                drawing subroutine (FillArea, FillBox).
  440. Returns:       nothing
  441. Uses:          nothing
  442. Supports:      all ASMLIB graphics modes except 256-color modes
  443. Example:
  444.  
  445. include asm.inc
  446.  
  447. extrn   fillbox:proc
  448. extrn   fillpattern:proc
  449.  
  450. .data
  451. x0      dw 25,10            ; first corner at (25,10); data is word size
  452. x1      dw 301,97           ; opposite corner at (301,97)
  453. pattern db 8 dup(10101010b),0
  454.  
  455. .code
  456. ; program fragment assumes DS:@data
  457.         .
  458.         .
  459.         lea   bx,pattern    ; DS:[BX] points to pattern string
  460.         call  fillpattern   ; define the pattern
  461.         sub   bx,8          ; DS:[BX] points to box corner data
  462.         call  fillbox       ; draw a patterned box
  463.  
  464.  
  465. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  466.  
  467. FORCEGMODE:    force ASMLIB to use one particular graphics mode
  468.                this is handy for two-monitor systems
  469. Source:        defgmode.asm
  470.  
  471. Call with:     AL = graphics mode to use
  472.                forcegmode does not change the actual screen mode; what
  473.                it does is to force ASMLIB's central graphics control
  474.                to ignore the system mode.  Call defgmode to restore
  475.                ASMLIB's internal flags to the default state.
  476. Returns:       nothing
  477. Uses:          nothing
  478. Supports:      all ASMLIB graphics modes (256-color modes not tested)
  479. Example:
  480.  
  481. include asm.inc
  482.  
  483. extrn   modecolor:proc, modemono:proc
  484. extrn   forcegmode:proc, gcolor:proc, defgmode:proc
  485.  
  486. .data
  487. gtext   db 'Graphics mode',0
  488. gpos    dd 0                   ; 2 words of zeros to position text
  489. ttext   db 'Text mode',0
  490.  
  491. .code
  492. ; program fragment assumes DS:@data
  493. ; I want text on the monochrome screen and 16-color graphics on the EGA
  494.         call   modecolor       ; switch to color monitor
  495.         mov    ax,10h          ; set up graphics mode
  496.         int    10h
  497.         mov    al,10h          ; tell ASMLIB to use mode 10h
  498.                                ; use AL = 13h for VGA 256-color modes
  499.                                ; use AL = 8 for Hercules (including InColor)
  500.         call   forcegmode      ; best to do this after the mode change
  501.         call   modemono        ; switch back to the monochrome monitor
  502.         mov    ax,010Ch        ; blue background, red foreground
  503.         call   gcolor
  504.         lea    si,gtext        ; point to graphics message
  505.         lea    dx,gpos         ; positioned at upper left corner
  506.         call   gprint          ; prints on EGA in graphics mode
  507.  
  508.         lea    si,ttext        ; point to text message
  509.         xor    dx,dx           ; upper left corner of text screen
  510.         mov    ah,7            ; normal color
  511.         call   tprint          ; display message on monochrome monitor
  512.         .
  513.         .
  514. ; sometime later, all done with this setup
  515.         call   defgmode        ; clear ASMLIB's internal graphics flags
  516.  
  517.  
  518. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  519.  
  520. GBASESEG:      change ASMLIB graphics base segment
  521. Source:        gbaseseg.asm ($graph.asm)
  522.  
  523. Call with:     AX = base segment address for alternate buffer
  524.                if AX = 0, default base segment is restored
  525.                GBaseSeg may be used to create and update off-screen graph
  526.                images, thus simulating multiple screen pages.
  527. Returns:       nothing
  528. Uses:          nothing
  529. Supports:      mode 04h, 05h, HGraph (monochrome only), 40h, 11h, 13h
  530.  
  531.                buffer size requirements:
  532.  
  533.                 mode 04h, 05h    16384 bytes
  534.                 HGraph, 40h      32768 bytes
  535.                 mode 11h         38400 bytes
  536.                 mode 13h          64000 bytes
  537.  
  538.                 GBaseSeg may also work with planar or bank-switched
  539.                 modes in a windowing multi-tasking enviornment, such
  540.                 as DesqView.  Feedback, please!!
  541.                 You must call GBaseseg AFTER switching the system to graphics
  542.                 mode, or it will not work; you must also call GBaseSeg with
  543.                 AX = 0 before changing from one graphics mode to another, or
  544.                 the default base segment may get messed up.
  545. Example:
  546.  
  547. .model medium
  548.  
  549. public myprog
  550. extrn  gbaseseg:proc, drawbox:proc
  551.  
  552. .data
  553. boxdata dw 0,0,319,199
  554.  
  555. .fardata
  556. screen1 db 64000 dup (0)     ; second screen for mode 13h
  557.  
  558. .code
  559. myprog proc
  560. ; program fragment assumes DS:@DATA
  561. ; mode 13h, 320x200x256 colors
  562.        mov     ax,13h
  563.        int     10h
  564. ; use alternate buffer
  565.        mov     ax,seg screen1
  566.        call    gbaseseg
  567.        lea     bx,linedata
  568.        call    drawbox
  569.  
  570. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  571.  
  572. GCENTER:       centers a string on a graphics screen
  573. Source:        gcenter.asm (gprint.asm, $graph.asm, strlen.asm, f8x14.asm)
  574.  
  575. GCENTERX:      centers a double-width string on a graphics screen
  576. Source:        gcenterx.asm (gprintx.asm, $graph.asm, strlen.asm, f8x14.asm)
  577.  
  578. Call with:     DS:[SI] pointing to the string to print
  579.                DS:[DX] pointing to x- and y-coordinates
  580.                the x-coordinate is a placeholder; GCenter calculates the
  581.                correct x value before calling GPrint.
  582.  
  583.                Colors, drawmodes and character sizes are the same as
  584.                for GPrint or GPrintX.
  585. Returns:       x = calculated x-coordinate
  586. Uses:          nothing; all registers and flags are saved.
  587. Supports:      all ASMLIB graphics modes
  588. Example:
  589.  
  590. include asm.inc
  591.  
  592. extrn   gcenter:proc
  593.  
  594. .data
  595. x       dw ?
  596. y       dw 2               ; print graph title 2 pixels down from the top
  597. title   db 'Graph title',0
  598.  
  599. .code
  600. ; program fragment assumes DS:@data
  601.         .
  602.         .
  603.         lea    si,title    ; DS:[SI] points to string
  604.         lea    dx,x        ; point to coordinates
  605.         call   gcenter     ; print the string, centered horizontally
  606.  
  607.  
  608. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  609.  
  610. GCLEAR:        clears the active portion of a graphics screen
  611.                uses background color
  612. Source:        gclear.asm ($graph.asm, $horiz.asm, others)
  613.  
  614. Call with:     no parameters
  615. Returns:       nothing
  616. Uses:          nothing
  617. Supports:      all ASMLIB graphics modes
  618. Example:
  619.  
  620. include asm.inc
  621.  
  622. extrn   gclear:proc
  623.  
  624. .code
  625.         .
  626.         .
  627.         .
  628.         call  gclear
  629.  
  630. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  631.  
  632. GCOLOR:        update color used by ASMLIB graphics
  633. Source:        gcolor.asm ($graph.asm)
  634.  
  635. Call with:     AL = foreground color
  636.                AH = background color
  637.  
  638.                for 4-color modes, colors may be 0-3
  639.                for 16-color modes, colors may be 0-15
  640.                for 256-color modes, colors may be 0-255
  641.  
  642. Returns:       nothing
  643. Uses:          nothing
  644. Supports:      all color graphics modes and mode 0Fh
  645.                GColor is ignored by 2-color modes
  646. Example:
  647.  
  648. include asm.inc
  649.  
  650. extrn   gcolor:proc
  651.  
  652. .code
  653.         .
  654.         .
  655.         .
  656.         mov   ah,bcolor      ; background color
  657.         mov   al,fcolor      ; foreground color
  658.         call  gcolor
  659.  
  660.  
  661. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  662.  
  663. GCOPY:         copies one page of graphics memory to another
  664. Source:        gcopy.asm ($graph.asm)
  665.  
  666. Call with:     BH = frompage
  667.                BL = topage
  668. Returns:       CF = error flag
  669.                 if CF = 0, no error
  670.                 if CF = 1, bad page number or frompage = topage
  671. Uses:          AX, CF
  672. Supports:      Hercules and InColor (with Use64k)
  673.                EGA/VGA modes 0Dh, 0Eh, 0Fh, 10h
  674.                Super13
  675. Example:
  676.  
  677. include asm.inc
  678.  
  679. extrn   gcopy:proc
  680.  
  681. .code
  682.         .
  683.         .
  684.         .
  685.         mov   bx,0001h       ; copy from page 0 to page 1
  686.         call  gcopy
  687.         jc    bad_page       ; uh oh, pages not supported
  688.  
  689.  
  690. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  691.  
  692. GCURSOR:       simulate text-mode cursor on graphics screen
  693. GUCURSOR:      simulate underscore cursor on graphics screen
  694. Source:        gcursor.asm ($graph.asm)
  695.  
  696. Call with:     DS:[DX] pointing to x- and y-coordinate word data
  697.                x and y are the coordinates of the UPPER LEFT corner of
  698.                a character block.  Note that text characters are
  699.                8 x-pixels wide and from 8 to 16 y-pixels high.
  700.  
  701.                GCursor and GUCursor maintain the simulated cursor while
  702.                the keyboard type-ahead buffer is empty.  GCursor shape
  703.                is an underscore when INSERT is off and a larger block
  704.                when INSERT is on.  GUCursor is an underscore regardless
  705.                of the state of the INSERT toggle.
  706. Returns:       nothing
  707. Uses:          AX, CX
  708. Supports:      all ASMLIB graphics modes
  709. Example:
  710.  
  711. include asm.inc
  712.  
  713. extrn   gcursor:proc, getkey:proc
  714.  
  715. .data
  716. x       dw 10,20        ; put the cursor in the character block at (10,20)
  717.  
  718. .code
  719. ; program fragment assumes DS:@data
  720.         .
  721.         .
  722.         .
  723.         lea   dx,x
  724.         call  gcursor
  725.         call  getkey    ; retrieve the key that was pressed
  726.  
  727.  
  728. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  729.  
  730. GETBITBLOCK:   saves a portion of a graphics screen in memory
  731. Source:        small & medium: bitblock.asm ($graph.asm, bb02.asm, bb04.asm
  732.                                bb06.asm, bb08.asm, bb10.asm, bb12.asm,
  733.                                bb14.asm)
  734.                huge: same as small & medium, + lowES2hi.asm & lowDS2hi.asm
  735.  
  736. Call with:     ES:[DI] pointing to memory buffer for the bit block
  737.                DS:[BX] pointing to x & y coordinate data
  738.  
  739.                Note that a bit block copied from a 4-plane mode may
  740.                only be restored to a 4-plane mode; likewise, a bit
  741.                block saved from a 2-color mode should be restored to
  742.                a 2-color mode or to a single bit plane of a 16-color
  743.                mode.
  744. Returns:       nothing
  745. Uses:          nothing
  746. Supports:      all ASMLIB graphics modes
  747.                memory models: small medium, huge
  748.  
  749. Example on next page
  750.  
  751.  
  752. ; example of GetBitBlock use
  753.  
  754. include asm.inc
  755.  
  756. extrn   bitblockbytes:proc, getbitblock:proc, putbitblock:proc
  757. extrn   halloc:proc
  758.  
  759. .data
  760. ptr     dw ?                ; use this to save pointer to bit block
  761. x0      dw 100,43,175,143   ; save from (100,43) to (175,143)
  762.  
  763. .code
  764. ; program fragment assumes DS:@data
  765.         .
  766.         .
  767.         lea   bx,x0         ; point to block corners
  768.         call  bitblockbytes ; calculate byte requirement
  769.         jc    too_big       ; error control
  770.         call  halloc        ; this example allocate the buffer from heap
  771.                             ; can't do this w/ huge bit blocks
  772.         jc    no_memory     ; more error control
  773.         mov   ptr,bx        ; save near address of bit block
  774.         push  ds
  775.         pop   es            ; ES = DS
  776.         mov   di,bx         ; ES:[DI] points to buffer
  777.         lea   bx,x0         ; DS:[BX] points to coordinate data
  778.         call  getbitblock
  779.         .
  780.         .
  781.  
  782. ; later . . .
  783.         lea   bx,x0         ; put the bit block back where you found it
  784.         push  ds
  785.         pop   es            ; ES = DS
  786.         mov   di,ptr        ; ES:[DI] points to buffer
  787.         call  putbitblock
  788.  
  789. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  790.  
  791. GETBITPLANE:   saves one plane of a bit block in memory
  792. Source:        small & medium: bitplane.asm ($graph.asm, bb02.asm, bb04.asm
  793.                                bb06.asm, bb08.asm, bb10.asm, bb12.asm,
  794.                                bb14.asm)
  795.                huge: same as small & medium, + lowES2hi.asm & lowDS2hi.asm
  796.  
  797. Call with:     ES:[DI] pointing to memory buffer for the bit block
  798.                DS:[BX] pointing to x & y coordinate data
  799.                AL = plane number to save
  800.                valid plane numbers are 0 - 3 in 16-color modes
  801.                                        0 & 2 in EGA monochrome mode
  802.  
  803.                In 16-color modes, EGA/VGA and InColor planes are:
  804.                 0 = blue, 1 = green, 2 = red, 3 = gray (or intensity)
  805.                In EGA monochrome mode, plane 0 = normal, plane 2 = blink
  806.                 or intensity
  807.                The actual colors each plane represents may change
  808.                depending on the values in the pallete registers.
  809.  
  810. Supports:      all 16-color modes plus EGA monochrome
  811.                other modes: GetBitPlane works like GetBitBlock
  812.                memory models: small, medium, huge
  813.  
  814.  
  815. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  816.  
  817. GETVIEW:       returns a pointer to the current view coordinates for
  818.                the active page
  819. Source:        getview.asm ($graph.asm)
  820.  
  821. Call with:     no parameters
  822.                most ASMLIB subroutines, except the GPrint series, Gload,
  823.                GCopy and GSave, limit their activity to the view region.
  824.                You may use the returned pointer to change the active
  825.                portion of the screen; be careful not to exceed the maximum
  826.                x1 and y1 values permitted by the current mode.  Also, x0
  827.                must always be less than x1 and y0 must always be less than
  828.                y1.
  829.                ASMLIB's defaults are:
  830.                 x0 = 0
  831.                 y0 = 0
  832.                 x1 = xmax
  833.                 y1 = ymax
  834.  
  835.                See also ResetView
  836.  
  837. Returns:       ES:[BX] pointing to the current view coordinates
  838. Uses:          ES, BX; all other registers and flags are saved
  839. Supports:      all ASMLIB graphics modes and pages
  840. Example:
  841.  
  842. include asm.inc
  843.  
  844. extrn   getview:proc
  845.  
  846. x0 EQU word ptr ES:[BX]
  847. y0 EQU word ptr ES:2[BX]
  848. x1 EQU word ptr ES:4[BX]
  849. y1 EQU word ptr ES:6[BX]
  850.  
  851. .code
  852.         .
  853.         .
  854.         .
  855.         call   getview
  856.  
  857.  
  858. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  859.  
  860. GLOAD:         loads a graphics screen saved as a disk file by GSave
  861. Source:        gsave.asm ($graph.asm)
  862.  
  863. Call with:     DS:[DX] pointing to the name of the file to load
  864.                the filename must be an ASCIIZ string
  865. Returns:       AX = MS-DOS error code
  866. Uses:          AX, BX, CX, flags
  867. Supports:      all ASMLIB graphics modes
  868. Example:
  869.  
  870. include asm.inc
  871.  
  872. extrn   gload:proc
  873.  
  874. .data
  875. filename db 'graph.bin',0
  876.  
  877. .code
  878. ; program fragment assumes DS:@data
  879.         .
  880.         .
  881.         lea   dx,filename
  882.         call  gload
  883.  
  884.  
  885. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  886.  
  887. GPAGE:         changes active and displayed graphics page
  888.                GPage changes ASMLIB's default graphics page and displays
  889.                the page.  See also UseGPage and ShowGPage.
  890. Source:        gpage1.asm ($graph.asm, $herc.asm, gpage.asm)
  891.  
  892. Call with:     BL = page number.  See table at start of this GRAPHICS.DOC
  893.                file.
  894. Returns:       if CF = 0, no problem
  895.                if CF = 1, bad page number requested
  896. Uses:          CF
  897. Supports:      EGA, VGA, Hercules, InColor: modes with more than one page
  898. Example:
  899.  
  900. include asm.inc
  901.  
  902. extrn   gpage:proc
  903.  
  904. .code
  905.         .
  906.         .
  907.         mov    bl,1          ; use and show page 1
  908.         call   gpage
  909.         jc     oops          ; uh oh, wrong mode
  910.  
  911. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  912.  
  913. GPRINT:        prints ASCIIZ string on a graphics screen
  914. Source:        gprint.asm ($graph.asm, f8x14.asm, $gp00.asm, $gp02.asm,
  915.                            $gp06.asm, $gp08.asm, $gp10.asm, others)
  916.  
  917. Call with:     DS:[SI] pointing to the ASCIIZ string
  918.                DS:[DX] pointing to x- and y-coordinate data
  919.                drawmodes supported by GPrint are:
  920.                 2 = foreground only; background pixels left alone
  921.                 1 = foreground and background pixels updated with
  922.                     current gcolor
  923.                 0 = foreground color is XORed with the existing screen
  924.                -1 = like drawmode 1, but foreground and background reversed
  925.                -2 = like drawmode 2, but uses background color
  926.                Any pixel position may be specified; does not wrap around
  927.                from right side of screen to left.  Default character size
  928.                is 8x8 for CGA modes and modes 0Dh, 0Eh and 13h, 8x14 for
  929.                others.
  930.                High ASCII characters are undefined in 8x8 pixel modes
  931.                unless you call SmallText sometime earlier in the program.
  932. Returns:       nothing
  933. Uses:          CX; all other registers and flags are saved
  934. Supports:      all ASMLIB graphics modes
  935.                not all drawmodes supported with CGA modes 04h and 05h
  936. Example:
  937.  
  938. include asm.inc
  939.  
  940. extrn   gprint:proc
  941.  
  942. .data
  943. string  db 'print this, if you will',0
  944. gpos    dw 0,0                          ; print at upper left corner
  945.  
  946. .code
  947. ; program fragment assumes DS:@data
  948.         .
  949.         .
  950.         .
  951.         lea   si,string
  952.         lea   dx,gpos
  953.         call  gprint
  954.  
  955. additional GPRINT information on next page
  956.  
  957. GPRINT will work with user-defined fonts up to 16 pixel rows high in all
  958. modes except CGA modes and modes 0Dh, 0Eh and 13h.  GPRINT reads a public
  959. data area in ASMSEG to determine the SEGMENT:OFFSET address of the font
  960. data, the number of pixel rows per character and the byte increment
  961. between sucessive character definitions.  Characters must be 8 pixels wide.
  962.  
  963. FONTDATA.ASM has the required font data:
  964.  
  965. public  fontseg
  966. fontseg dw SEG f8x14    ; segment address of user-loaded font (8x14 default)
  967.         dw OFFSET f8x14 ; offset address of user-loaded font (8x14 default)
  968.         db 14           ; byte size of character
  969.         db 14           ; bytes from start of one char to start of next
  970.  
  971. Example:
  972.  
  973. include asm.inc
  974.  
  975. ASMSEG  segment byte public
  976. extrn   fontseg:word
  977. ASMSEG  ends
  978.  
  979. .data
  980. fname   db 'c:\ramfont\italics.fnt',0   ; 8x14 characters
  981. fbuffer db 4096 dup (0)                 ; all RAMFont fonts are 4096 bytes
  982. ; the fonts supplied by Hercules with the Graphics Card Plus and InColor
  983. ; card are a variety of sizes, but in each font file the byte increment
  984. ; is always 16 bytes
  985.  
  986. .code
  987.         .
  988.         .
  989.         mov     ax,@data
  990.         mov     ds,ax
  991.         lea     dx,fname
  992.         mov     ax,3D00h        ; open file for read
  993.         int     21h
  994.         mov     bx,ax           ; copy file handle to BX
  995.         lea     dx,fbuffer      ; DS:[DX] points to buffer
  996.         mov     cx,4096
  997.         mov     ah,3Fh          ; read file
  998.         int     21h
  999.         mov     ah,3Eh          ; close file
  1000.         int     21h
  1001.         mov     ax,ASMSEG
  1002.         mov     es,ax
  1003.         assume  es:ASMSEG
  1004.         mov     es:fontseg,ds   ; update segment address of new font
  1005.         mov     es:fontseg+2,dx ; update offset address of new font
  1006.         mov     es:fontseg+4,(16 shl 8) OR 14
  1007.                                 ; 14-pixel row character
  1008.                                 ; 16 bytes between character definitions
  1009.  
  1010. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1011.  
  1012. GPRINTDOWN:    prints ASCIIZ string vertically on graph screen
  1013. GPRINTUP:      prints ASCIIZ string vertically on graph screen
  1014. Source:        gprint.asm ($graph.asm, f8x14.asm, $gp00.asm, $gp02.asm,
  1015.                            $gp06.asm, $gp08.asm, $gp10.asm, others)
  1016.  
  1017. Call with:     same as GPrint
  1018.                rotates each character 90 degrees and prints from top
  1019.                downward or from bottom upward.  Character size 8x8.
  1020.  
  1021.                Returned data and registers used same as GPrint
  1022. Example:       see GPrint.
  1023.  
  1024.  
  1025. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1026.  
  1027. GPRINTX:       print string on a graphics screen, double width
  1028. GPRINT2X:      print string on a graphics screen, double size
  1029. GPRINTDOWNX:   print string vertically on graph screen, 2x width
  1030. GPRINTDOWN2X:  print string vertically on graph screen, 2x size
  1031. GPRINTUPX:     print string vertically on graph screen, 2x width
  1032. GPRINTUP2X:    print string vertically on graph screen, 2x size
  1033. Source:        gprintx.asm ($graph.asm, f8x14.asm, $gp00.asm, $gp02.asm,
  1034.                             $gp06.asm, $gp08.asm, $gp10.asm, others)
  1035.  
  1036.  
  1037.                Variations of GPrint and GPrintDOWN/GPrintUP;
  1038.                GPrintx, GPrintDOWNx and GPrintUPx print characters
  1039.                which are twice as wide as normal; 2x subroutines
  1040.                print the characters twice as wide and twice as high
  1041.                as normal.
  1042.  
  1043.                Parameters, supported modes and drawmodes are same as
  1044.                GPrint.  GPrintx and GPrint2x also work with user-defined
  1045.                fonts.  See GPrint.
  1046. Example:       see GPrint.
  1047.  
  1048.  
  1049. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1050.  
  1051. GSAVE:         saves a graphics screen as a disk file
  1052.                does not compress image
  1053. Source:        gsave.asm ($graph.asm)
  1054.  
  1055. Call with:     DS:[DX] pointing to ASCIIZ filename
  1056.                disk space requirements vary depending on graphics mode:
  1057.  
  1058.                  HGraph  (mono)     32,768 bytes
  1059.                  HGraph  (InColor) 131,072 bytes
  1060.                  Super13           128,000 bytes
  1061.                  Super13a          172,800 bytes
  1062.                  VESA6Ah           240,000 bytes
  1063.                  XMode16  varies; up to 240,000 bytes
  1064.                  04h/05h/06h        16,384 bytes
  1065.                  0Dh                32,000 bytes
  1066.                  0Eh                64,000 bytes
  1067.                  0Fh                56,000 bytes
  1068.                  10h               112,000 bytes
  1069.                  11h                38,400 bytes
  1070.                  12h               153,600 bytes
  1071.                  13h                64,000 bytes
  1072.  
  1073. Returns:       if AX <> 0, AX = MS-DOS error code
  1074.                if AX = 0, no error
  1075. Uses:          AX, BX, CX, flags
  1076. Supports:      all ASMLIB graphics modes
  1077. Example:
  1078.  
  1079. include asm.inc
  1080.  
  1081. extrn   gsave:proc
  1082.  
  1083. .data
  1084. filename db 'graph.bin',0
  1085.  
  1086. .code
  1087. ; program fragment assumes DS:@data
  1088.         .
  1089.         .
  1090.         .
  1091.         lea   dx,filename         ; point to ASCIIZ filename
  1092.         call  gsave               ; save graph
  1093.         or    ax,ax               ; was there a problem?
  1094.         jnz   oops                ; do some error control if so
  1095.  
  1096.  
  1097. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1098.  
  1099. LINEPATTERN:   defines an optional pattern for DrawLine and DrawBox
  1100. Source:        lpattern.asm ($graph.asm)
  1101.  
  1102. Call with:     DS:[BX] pointing to an ASCIIZ string of up to 8 characters.
  1103.                The bit patterns in each character are used to make dashed
  1104.                or dotted lines. For drawmodes > 0, each pixel in the line
  1105.                is updated with the foreground color if the corresponding
  1106.                bit in the bit pattern is 1.  If the bit in the bit pattern
  1107.                is 0, the corresponding pixel in the line is treated as a
  1108.                background pixel.  LinePattern must be called before each
  1109.                call to a subroutine in drawline.obj if you want the line
  1110.                pattern to be used.
  1111.  
  1112.                drawmodes supported are:
  1113.                (monochrome modes)
  1114.                 2 = update foreground pixels only
  1115.                 1 = update foreground and background pixels
  1116.                 0 = XOR the foreground color with the existing image
  1117.                -1 = like drawmode 1, but foreground and background colors
  1118.                     are reversed
  1119.                -2 = like drawmode 2, but foreground and background colors
  1120.                     are reversed
  1121.                (color modes)
  1122.                same as monochrome, plus:
  1123.                 3 = OR the foreground pixels with the pre-existing screen
  1124.                -3 = OR the background pixels with the pre-existing screen
  1125.                 4 = AND the foreground pixels with the pre-existing screen
  1126.                -4 = AND the background pixels with the pre-existing screen
  1127.  
  1128. Returns:       nothing
  1129. Uses:          nothing
  1130. Supports:      all ASMLIB graphics modes
  1131. Example:
  1132.  
  1133. include asm.inc
  1134.  
  1135. extrn   linepattern:proc, drawline:proc
  1136.  
  1137. .data
  1138. x0      dw 25,10,301,97          ; line endpoints at (25,10) & (301,97)
  1139. pattern db 4 dup(32,64),0        ; 8 bytes past x0
  1140.  
  1141. .code
  1142. ; program fragment assumes DS:@data
  1143.         .
  1144.         .
  1145.         lea   bx,pattern         ; DS:[BX] points to bit pattern
  1146.         call  linepattern        ; let drawline know what pattern to use
  1147.         sub   bx,8               ; point to line endpoint data
  1148.         call  drawline           ; draw a patterned line
  1149.  
  1150. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1151.  
  1152. PUTBITBLOCK:   restores bit block saved by GetBitBlock
  1153. PUTBITPLANE:   restores bit plane saved by GetBitPlane
  1154. Source:        same as GetBitBlock or GetBitPlane
  1155.  
  1156. Call with:     DS:[BX] pointing to upper left corner coordinates
  1157.                ES:[DI] pointing to buffer with stored bit block
  1158.                 PutBitPlane: AL = plane number
  1159.                 valid plane numbers for 16-color modes are 0 - 3
  1160.                                     for EGA mode 11h       0 & 2
  1161.  
  1162.                Drawmodes supported are:
  1163.                 mode 13h, super13, super13a:
  1164.                  1 = replace existing screen area with bit block
  1165.                  2 = replace existing screen with non-zero pixels
  1166.                      in bit block
  1167.  
  1168.                 HGraph (InColor):
  1169.                  4 = AND the bit block with the existing screen
  1170.                  3 = OR the bit block with the existing screen
  1171.                  1,2 = replace existing screen area with bit block
  1172.                  0 = XOR the bit block with the existing image
  1173.                 -1,-2 = replace existing screen area with inverse bit block
  1174.  
  1175.                 16-color EGA/VGA-type modes and mode 0Fh:
  1176.                  same as InColor, plus:
  1177.                 -3 = OR the inverse bit block with the existing screen
  1178.                 -4 = AND the inverse bit block with the existing screen
  1179.  
  1180.                 mode 04h, 05h, 06h, HGraph (mono), 11h:
  1181.                  4, 1, 0, -1 same as InColor
  1182.                  2, 3 = combine non-zero pixels in the bit block with the
  1183.                         pre-existing image
  1184.                 -2 = combine non-zero pixel in the inverse bit block with
  1185.                      the pre-existing screen image
  1186.  
  1187. Returns:       nothing
  1188. Uses:          nothing
  1189. Supports:      all ASMLIB graphics modes
  1190. Example:       see GetBitBlock
  1191.  
  1192.  
  1193. bit block formats explained on following pages
  1194.  
  1195.  
  1196. ; BIT BLOCK FORMATS
  1197.  
  1198. ; mode 04h, 05h, 06h Hercules monochrome, 11h, and bit planes
  1199. ;
  1200. ; the first word in the buffer is the number of pixel rows (vertical)
  1201. ; in the bit block; the second word is the number of bytes per screen row;
  1202. ; the fifth byte is a bit mask for the last byte of each pixel row.
  1203. ; The bit mask = 0FFh for byte-aligned bit blocks.
  1204.  
  1205. bblock  dw 15,5              ; 15 rows, 5 bytes per row
  1206.         db 11111110b         ; bit mask for right end of pixel row
  1207.                              ; bit block data follows:
  1208.                              ;  15 rows, 5 bytes per row
  1209.         db 00000000b,10000000b,00000000b,10000000b,00000010b
  1210.         db 00000001b,11000000b,00000001b,11000000b,00000110b
  1211.         db 00000011b,11100000b,00000011b,11100000b,00001100b
  1212.         db 00000111b,01110000b,00000111b,01110000b,00011000b
  1213.         db 00001110b,00111000b,00001110b,00111000b,00110000b
  1214.         db 00011100b,00011100b,00011100b,00011100b,01100000b
  1215.         db 00000001b,11000000b,00000001b,11000000b,11000000b
  1216.         db 00000001b,11000000b,00000001b,11000000b,01100000b
  1217.         db 00000001b,11000000b,00000001b,11000000b,00110000b
  1218.         db 00000001b,11000000b,00000001b,11000000b,00011000b
  1219.         db 00000001b,11000000b,00000001b,11000000b,00001100b
  1220.         db 00000001b,11000000b,00000001b,11000000b,00000110b
  1221.         db 00000001b,11000000b,00000001b,11000000b,00000010b
  1222.         db 00000001b,11000000b,00000001b,11000000b,00000000b
  1223.         db 00000001b,11000000b,00000001b,11000000b,00000000b
  1224.  
  1225. ; 16-color modes: 0Dh, 0Eh, 10h, 12h, 6Ah, xmode16, InColor:
  1226. ; same as above, except there are 4 planes of bit block data
  1227. ; i. e., 4 groups of 15-row, 5-byte data; plane 3 is the first
  1228. ; block, followed by planes 2, 1, and 0.
  1229.  
  1230. ; EGA monochrome mode: 0Fh
  1231. ; similar to 16-color modes, but there are only 2 groups of bit
  1232. ; block data instead of 4
  1233.  
  1234.  
  1235. ; 256-color modes on next page
  1236.  
  1237.  
  1238. ; BIT BLOCK FORMATS
  1239.  
  1240. ; mode 13h: no bit mask in the bit block header
  1241.  
  1242. red     equ 12                    ; bright red
  1243. blue    equ 1                     ; blue
  1244.  
  1245. bblock  dw 12,5                   ; 12 rows, 5 bytes per row
  1246.         db red, red, blue,red, red
  1247.         db red, blue,red, blue,red
  1248.         db blue,red, red, red, blue
  1249.         db red, red, blue,red, red
  1250.         db red, blue,red, blue,red
  1251.         db blue,red, red, red, blue
  1252.         db red, red, blue,red, red
  1253.         db red, blue,red, blue,red
  1254.         db blue,red, red, red, blue
  1255.         db red, red, blue,red, red
  1256.         db red, blue,red, blue,red
  1257.         db blue,red, red, red, blue
  1258.  
  1259. ; super13, super13a: no bit mask in the bit block header, x & y
  1260. ; orienation of data is reversed for speed
  1261. ; this example is the same pattern shown for mode 13h, above
  1262.  
  1263. red     equ 12                    ; bright red
  1264. blue    equ 1                     ; blue
  1265.  
  1266. bblock  dw 12,5                   ; 12 rows, 5 bytes per row
  1267.         db red, red, blue,red, red, blue,red, red, blue,red, red, blue
  1268.         db red, blue,red, red, blue,red, red, blue,red, red, blue,red
  1269.         db blue,red, red, blue,red, red, blue,red, red, blue,red, red
  1270.         db red, blue,red, red, blue,red, red, blue,red, red, blue,red
  1271.         db red, red, blue,red, red, blue,red, red, blue,red, red, blue
  1272.  
  1273.  
  1274. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1275.  
  1276. PUTDOT:        change a pixel on a graphics screen
  1277. Source:        putdot.asm ($graph.asm, $putdot.asm, others)
  1278.  
  1279. Call with:     DS:[BX] pointing to x & y coordinates
  1280.                Drawmodes supported are:
  1281.                (monochrome)
  1282.                 1 = set pixel
  1283.                 0 = toggle pixel
  1284.                -1 = erase pixel
  1285.  
  1286.                (color modes)
  1287.                 3 = OR foreground color with pre-existing pixel
  1288.                 1, 2 = replace pixel with foreground color
  1289.                 0 = XOR foreground color with pre-existing pixel
  1290.                -1, -2 = replace pixel with background color
  1291.                -3 = OR background color with pre-existing pixel
  1292. Returns:       if CF = 0, no error
  1293.                if CF = 1, pixel coordinates outside active view area
  1294. Uses:          CF; all other registers and flags are saved
  1295. Supports:      all ASMLIB graphics modes
  1296. Example:
  1297.  
  1298. include asm.inc
  1299.  
  1300. extrn   putdot:proc
  1301.  
  1302. .data
  1303. extrn   drawmode:byte
  1304. x       dw 100,117            ; pixel at x = 100, y = 117
  1305.  
  1306. .code
  1307. ; program fragment assumes DS:@data
  1308.         .
  1309.         .
  1310.         .
  1311.         mov   drawmode,1      ; use foreground color
  1312.         lea   bx,x            ; point to pixel coordinates
  1313.         call  putdot
  1314.  
  1315.  
  1316.  
  1317. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1318.  
  1319. GETDOT:        determine pixel value on graphics screen
  1320. Source:        getdot.asm ($graph.asm, $getdot.asm, others)
  1321.  
  1322. Call with:     DS:[BX] pointing to pixel coordinate data
  1323. Returns:       if CF = 0, AX = pixel value
  1324.                if CF = 1, pixel coordinates outside active view area
  1325. Uses:          AX, CF
  1326. Supports:      all ASMLIB graphics modes
  1327. Example:
  1328.  
  1329. include asm.inc
  1330.  
  1331. extrn   getdot:proc
  1332.  
  1333. .data
  1334. x       dw 10,10             ; pixel at (10,10)
  1335.  
  1336. .code
  1337. ; program fragment assumes DS:@data
  1338.         .
  1339.         .
  1340.         .
  1341.         lea    bx,x          ; point to pixel coordinates
  1342.         call   getdot        ; get pixel value
  1343.         jc     out_of_bounds ; oops
  1344.  
  1345.  
  1346.  
  1347. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1348.  
  1349. RESETVIEW:     restores default view area on active graphics page and
  1350.                returns a pointer to the view data
  1351. Source:        view.asm ($graph.asm)
  1352.  
  1353. Call with:     no parameters
  1354.                ResetView restores the default full screen view area.
  1355.                The far pointer returned points to ASMLIB's data area in
  1356.                $graph.obj for the active graphics page's view coordinates.
  1357. Returns:       ES:[BX] pointing to the active page's view data.
  1358. Uses:          ES, BX; all other registers and flags are saved
  1359. Supports:      all ASMLIB graphics modes
  1360. Example:
  1361.  
  1362. include asm.inc
  1363.  
  1364. extrn   resetview:proc
  1365.  
  1366. x0 EQU word ptr ES:[BX]
  1367. y0 EQU word ptr ES:2[BX]
  1368. x1 EQU word ptr ES:4[BX]
  1369. y1 EQU word ptr ES:6[BX]
  1370.  
  1371. .code
  1372.         .
  1373.         .
  1374.         .
  1375.         call  resetview
  1376.  
  1377.  
  1378.  
  1379. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1380.  
  1381. SHOWGPAGE:     change graphics page displayed on screen
  1382.                See also UseGPage and GPage.
  1383. Source:        gpage1.asm ($graph.asm, $herc.asm)
  1384.  
  1385. Call with:     BL = page number
  1386. Returns:       Carry Flag = error code
  1387.                if CF = 0, no error
  1388.                if CF = 1, bad page number
  1389. Uses:          CF
  1390. Supports:      HGraph (mono and InColor), modes 0Dh, 0Eh, 0Fh, 10h, Super13
  1391. Example:
  1392.  
  1393. include asm.inc
  1394.  
  1395. extrn   showgpage:proc
  1396.  
  1397. .code
  1398.         .
  1399.         .
  1400.         .
  1401.         mov   bl,1           ; show page 1
  1402.         call  showgpage
  1403.         jc    no_page_1      ; no page 1 for this mode
  1404.  
  1405. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1406.  
  1407. SHOWGPLANE:    show one or more planes of multi-plane EGA/VGA screen
  1408. Source:        gplane.asm ($graph.asm)
  1409.  
  1410. Call with:     AL = plane mask
  1411.                Bits set in the plane mask correspond to the plane displayed.
  1412.                ASMLIB's default mask is 00001111b, enabling all 4 planes.
  1413. Returns:       CF = error flag
  1414.                if CF = 0, no error
  1415.                if CF = 1, bad plane mask or graphics mode
  1416. Uses:          CF
  1417. Supports:      EGA & VGA 16-color modes, including VESA 6Ah, xmode16
  1418.                    and SVGA16
  1419.                EGA monochrome: planes 0 and 2
  1420.                    (mask = 00000101b for both planes)
  1421.                Hercules InColor
  1422. Example:
  1423.  
  1424. include asm.inc
  1425.  
  1426. extrn   showgplane:proc
  1427.  
  1428. .code
  1429.         .
  1430.         .
  1431.         .
  1432.         mov   al,00000101b      ; show planes 0 and 2
  1433.         call  showgplane
  1434.         jc    error             ; error control
  1435.  
  1436.  
  1437.  
  1438. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1439.  
  1440. SMALLTEXT:     change GPrint, GPrintX and GPrint2X default to 8x8 characters
  1441.                in Hercules and modes 10h, 11h, 12h; makes 8x8-size
  1442.                high ASCII characters available to GPrint in all modes
  1443. STDTEXT:       restore GPrint default characters (see GPrint)
  1444. Source:        smalltxt.asm (f8x8.asm, $graph.asm)
  1445.  
  1446. Call with:     no parameters
  1447. Returns:       nothing
  1448. Uses:          nothing; all registers and flags are saved
  1449. Example:
  1450.  
  1451. include asm.inc
  1452.  
  1453. extrn   smalltext:proc, stdtext:proc
  1454.  
  1455. .code
  1456.         .
  1457.         .
  1458.         .
  1459. ; make GPrint use the small 8x8 characters
  1460. ; make sure high ASCII characters are available
  1461.         call   smalltext
  1462.         .
  1463.         .
  1464.  
  1465. ; sometime later, I want to use larger 8x14 characters
  1466.         call   stdtext
  1467.  
  1468.  
  1469. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1470.  
  1471. UC2SYS:        convert user-defined coordinates to system coordinates
  1472. Source:        uc2sys.asm ($graph.asm)
  1473.  
  1474. Call with:     DS:[BX] pointing to (x0,y0,x1,y1) coordinates in
  1475.                user-defined format
  1476.                assumes DS:@data
  1477. Returns:       DS:[BX] pointing to (x0,y0,x1,y1) coordinates in system
  1478.                format
  1479.                UCINIT and UC2SYS allow the programmer to define a
  1480.                graph coordinate system to fit the data, and converts
  1481.                the system's y-orientation from top-to-bottom to the more
  1482.                familiar bottom-to-top
  1483.                US2SYS maintains a separate data area for converted
  1484.                coordinates; the input coordinates are not changed
  1485. Uses:          BX
  1486. Supports:      all ASMLIB graphics modes; user-defined coordinates
  1487.                from -32767 to +32767; see also UCINIT
  1488. Example:       see UCINIT
  1489.  
  1490.  
  1491. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1492.  
  1493. UCINIT:        specify user-defined coordinates
  1494. Source:        uc2sys.asm ($graph.asm)
  1495.  
  1496. Call with:     DS:[BX] pointing to desired xmin, ymin, xmax, ymax
  1497.                coordinates (xmax-xmin < 32767, ymax-ymin < 32767)
  1498.                assumes DS:@data
  1499.                ASMLIB's default user coordinates are (0,0,1000,1000)
  1500. Returns:       nothing
  1501. Uses:          nothing
  1502. Example:
  1503.  
  1504. ; I'm plotting a graph on the screen with x-axis data from 1983 to 2007
  1505. ; and y-axis data from -72 to 140
  1506. ; I'll leave some space on each side for titles, etc.
  1507.  
  1508. extrn   ucinit:proc, uc2sys:proc
  1509. extrn   drawbox:proc
  1510.  
  1511. .data
  1512. x0      dw 1975    ; xmin
  1513. y0      dw -80     ; ymin
  1514. x1      dw 2014    ; xmax
  1515. y1      dw 148     ; ymax
  1516.  
  1517. .code
  1518. ; program fragment assumes DS:@data
  1519.         .
  1520.         .
  1521.         .
  1522. ; establish coordinates
  1523.         lea     bx,x0
  1524.         call    ucinit
  1525.  
  1526. ; draw a box arouund the graph
  1527.         mov     x0,1983
  1528.         mov     y0,-72
  1529.         mov     x1,2007
  1530.         mov     y1,140
  1531.         lea     bx,x0
  1532.         call    uc2sys
  1533.         call    drawbox
  1534.  
  1535. ; SEE ALSO BARGRAPH.ASM EXAMPLE PROGRAM
  1536.  
  1537.  
  1538. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1539.  
  1540. USEGPAGE:      changes active graphics page used by ASMLIB
  1541.                does not change page displayed (see GPage and ShowGPage)
  1542. Source:        gpage.asm ($graph.asm, $herc.asm)
  1543.  
  1544. Call with:     BL = page number
  1545. Returns:       if CF = 0, no error
  1546.                if CF = 1, bad page number
  1547. Uses:          CF
  1548. Supports:      HGraph (mono and InColor) with Use64k
  1549.                EGA and VGA: modes with more than one page
  1550. Example:
  1551.  
  1552. include asm.inc
  1553.  
  1554. extrn   usegpage:proc
  1555.  
  1556. .code
  1557.         .
  1558.         .
  1559.         mov   bl,1
  1560.         call  usegpage
  1561.         jc    oops
  1562.  
  1563.  
  1564.  
  1565. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1566.  
  1567. VIEWLIMIT:     determine current mode's maximum dimensions
  1568. Source:        view.asm ($graph.asm)
  1569.  
  1570. Call with:     no parameters
  1571. Returns:       ES:[BX] pointing to xmax
  1572.                ES:2[BX] pointing to ymax
  1573. Uses:          ES, BX
  1574. Supports:      all ASMLIB graphics modes
  1575. Example:
  1576.  
  1577. include asm.inc
  1578.  
  1579. extrn   viewlimit:proc
  1580.  
  1581. .code
  1582.         .
  1583.         .
  1584.         call  viewlimit
  1585.  
  1586.