home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / asmutil / asmlib37.zip / TEXT.DOC < prev   
Text File  |  1993-04-05  |  32KB  |  941 lines
  1.  
  2. ******************************  TEXT MODE  *******************************
  3.  
  4. ASMLIB Text mode video subroutines (C) Copyright 1991 - 1993 Douglas Herr
  5. All rights reserved
  6.  
  7. Screen writing in TEXT mode
  8.  
  9. ASMLIB subroutines write directly to the video memory buffer, except
  10. where noted.  ASMLIB detects the default display type and screen
  11. dimensions.  ASMLIB assumes that CGA equipment requires "snow" control
  12. and behaves accordingly.  In text modes, ASMLIB does not distinguish
  13. between CGA and MCGA equipment.
  14.  
  15. Multiple pages of video memory are available except with MDA video adapters.
  16.  
  17. Pages supported by ASMLIB are shown below:
  18.  
  19. video system   screen size    ASMLIB support   BIOS support
  20. -------------  -----------    --------------   ---------------
  21. MDA            80 x 25        page  0          page  0
  22. CGA, MCGA      80 x 25        pages 0 - 3      pages 0 - 3
  23. CGA, EGA, VGA  40 x 25        pages 0 - 7      pages 0 - 7
  24. EGA, VGA       80 x 25        pages 0 - 7      pages 0 - 7
  25. EGA            80 x 43        pages 0 - 3      pages 0 - 3
  26. VGA            80 x 50        pages 0 - 3      pages 0 - 3
  27. EEGA          132 x 25        pages 0 - 3      pages 0 - 3
  28. EEGA          132 x 44        pages 0 & 1      pages 0 & 1
  29. PEGA          132 x 25        pages 0 - 3      pages 0 - 3
  30. PEGA          132 x 43        pages 0 & 1      pages 0 & 1
  31. HGC, HGC+, InC 80 x 25        pages 0 - 15     page  0
  32. HGC+, InC      90 x 25        pages 0 - 13     page  0
  33. HGC+, InC      80 x 43        page  0          page  0
  34. HGC+, InC      90 x 43        page  0          page  0
  35.  
  36.    ASMLIB subroutines assume that rows are the vertical dimension and
  37.    columns are the horizontal dimension of a text-mode screen.  The upper
  38.    left corner of the screen is at row=0 and col=0
  39.  
  40.  
  41. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  42.  
  43. ANSICOLOR:   determines color attribute used by ANSI device driver.
  44.              See also IsANSI.
  45. Source:      anscolor.asm
  46.  
  47. Call with:   no parameters
  48. Returns:     AH = color attribute
  49. Uses:        AX
  50. Example:
  51.  
  52.        call  ansicolor         ; get ANSI screen color in AH
  53.  
  54.  
  55. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  56.  
  57. BLINKOFF:    disable blinking attriutes; enable bright background attributes
  58. BLINKON:     enable blinking attriutes; disable bright background attributes
  59. Source:      blink.asm
  60.  
  61. Call with:   no parameters
  62. Returns:     nothing
  63. Uses:        nothing; all registers and flags are saved
  64. Supports:    All ASMLIB text modes
  65. Example:
  66.  
  67.       call  blinkoff             ; turn blinking attributes into bright
  68.                                  ; background attributes
  69.  
  70.       call  blinkon              ; turn bright background attributes into
  71.                                  ; blinking attributes
  72.  
  73.  
  74.  
  75. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  76.  
  77. CRTINFO:     central control for ASMLIB Text subroutines; determines
  78.              active video system, screen size, page offset.
  79. Source:      crtinfo.asm
  80.  
  81. Call with:   AH = 0 for page 0 information
  82.              AH = -1 to calculate active page address
  83. Returns:     AL = screen rows
  84.              CH = screen columns
  85.              BX:[SI] = video buffer address
  86.              DX = 3DAh if CGA or MCGA, 0 if not CGA
  87.                DX is used to monitor screen retrace, to avoid "snow"
  88.                on older CGA systems.  CRTINFO does not distinguish between
  89.                CGA and MCGA equipment; MCGA does not require snow control.
  90.                You may use GetCRT to determine if an MCGA is installed
  91.                and turn ASMLIB's snow control off with SnowOFF if the system
  92.                has an MCGA.
  93. Uses:        ES, AX, BX, CX, DX, SI, flags
  94. Supports:    all ASMLIB text modes
  95.  
  96.  
  97. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  98.  
  99. CURSORCOLOR: set cursor color and enable color palette (InColor only)
  100. Source:      curscolor.asm ($herc.asm)
  101.  
  102. Call with:   AH = color attribute (1 - 15)
  103. Returns:     if CF = 0, no error
  104.              if CF = 1, InColor card not installed
  105. Uses:        Carry Flag
  106. Supports:    Hercules InColor card
  107. Example:
  108.  
  109. extrn   cursorcolor:proc
  110.  
  111. .code
  112.         .
  113.         .
  114.         .
  115.         mov   ah,14        ; bright yellow cursor
  116.         call  cursorcolor  ; enable InColor palette, set cursor color
  117.  
  118.  
  119.  
  120. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  121.  
  122. CURSOROFF:   make hardware cursor invisible at present location
  123. Source:      cursor.asm
  124.  
  125. Call with:   no parameters
  126. Returns:     nothing
  127. Uses:        nothing
  128. Supports:    CGA, MCGA, MDA, HGC, HGC+, InC, EGA, PEGA, EEGA, VGA: text mode
  129. Example:     call  cursoroff
  130.  
  131.  
  132. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  133.  
  134. CURSORON:    move cursor to (row, col) and update cursor shape
  135.              Cursor shape is underscore if INSERT is off, larger block
  136.              if INSERT is on.  See also UCursorON.
  137. Source:      cursor.asm (crtinfo.asm)
  138.  
  139. Call with:   DH = row offset from top of screen
  140.              DL = column offset from left side
  141. Returns:     nothing
  142. Uses:        AX
  143. Supports:    CGA, MCGA, MDA, HGC, HGC+, InC, EGA, PEGA, EEGA, VGA: text mode
  144. Example:     mov    dh,row        ; vertical coordinate on text screen
  145.              mov    dl,column     ; horizontal coordinate
  146.              call   cursoron
  147.  
  148.  
  149.  
  150. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  151.  
  152. GETSCREEN:   save a screen page to a memory buffer
  153. PUTSCREEN:   copy a saved screen page to the video buffer
  154. Source:      screen.asm (crtinfo.asm, $wcopy.asm)
  155.  
  156. Call with:   DS:[SI] pointing to memory buffer
  157. Returns:     nothing
  158. Uses:        nothing; all flags and registers are saved
  159. Supports:    All ASMLIB text modes; includes CGA snow control
  160. Example:     see ScreenMem for example
  161.  
  162.  
  163. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  164.  
  165. HSCROLL:     scroll a portion of the screen left or right.
  166. Source:      hscroll.asm (a$wdata.asm, $wcopy.asm, a$putw.asm, $exit.asm)
  167.  
  168. Call with:   DS:[BX] pointing to corner coordinates
  169.              AH = color attribute for cleared columns
  170.              CX = number of columns to scroll
  171.                scrolls left if CX > 0, scrolls right if CX < 0
  172.                clears area if CX = 0
  173. Returns:     nothing
  174. Uses:        nothing
  175. Supports:    All ASMLIB text modes; includes CGA snow control
  176. Example:
  177.  
  178. .data
  179.  
  180. wdata        dw     10          ; row0
  181.              dw     10          ; column0
  182.              dw     20          ; row1
  183.              dw     40          ; column1
  184.  
  185. .code
  186.  
  187.              .
  188.              .
  189.              .
  190.              lea    bx,wdata    ; DS:[BX] points to window coordinates
  191.              mov    ah,color    ; AH = color attribute for cleared columns
  192.              mov    cx,columns
  193.              call   hscroll     ; to clear entire window, columns = 0
  194.  
  195.  
  196.  
  197. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  198.  
  199. PAINT:       change all color attributes on a text-mode screen
  200.              without re-printing the text
  201. Source:      paint.asm (crtinfo.asm, a$paint.asm)
  202.  
  203. Call with:   AH = new color attribute
  204. Returns:     nothing
  205. Uses:        nothing
  206. Supports:    All ASMLIB text modes; includes CGA snow control
  207. Example:     mov   ah,newcolor
  208.              call  paint
  209.  
  210.  
  211. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  212.  
  213. RECOLOR:     change selected color attributes on a text-mode screen
  214.              Replaces oldcolor attribute with newcolor, without
  215.              re-printing the text.
  216. Source:      recolor.asm (crtinfo.asm, a$recolr.asm)
  217.  
  218. Call with:   AL = color to replace
  219.              AH = new color attribute
  220. Returns:     nothing
  221. Uses:        nothing
  222. Supports:    All ASMLIB text modes; includes CGA snow control
  223. Example:     mov   al,oldcolor
  224.              mov   ah,newcolor
  225.              call  recolor
  226.  
  227.  
  228. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  229.  
  230. SCREENMEM:   calculate bytes required to save screen page
  231.              Used with GetScreen and PutScreen.
  232. Source:      smem.asm (crtinfo.asm)
  233.  
  234. Call with:   no parameters
  235. Returns:     AX = number of bytes required
  236. Uses:        AX
  237. Example:     call  screenmem
  238.              call  halloc             ; this example uses near heap memory
  239.              jc    drat
  240.              mov   saved_pointer, bx
  241.              mov   si,bx
  242.              call  getscreen          ; save the screen
  243.                .
  244.                .
  245.                .
  246.              mov   si,saved_pointer
  247.              call  putscreen          ; restore the initial screen
  248.  
  249.  
  250. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  251.  
  252. SHOWTPAGE:   change video page shown on screen
  253. Source:      tpage.asm (crtinfo.asm, $herc.asm)
  254.  
  255. Call with:   BL = page number
  256. Returns:     AX = error code
  257.              0 = no error
  258.              -1 = bad page number
  259. Uses:        AX
  260. Supports:    All ASMLIB text modes (except MDA equipment)
  261. Example:     mov    bl,1               ; show page 1
  262.              call   showtpage
  263.  
  264.  
  265.  
  266. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  267.  
  268. SNOWOFF:     disables CGA snow control
  269. SNOWON:      enables CGA snow control (ASMLIB default)
  270. Source:      crtinfo.asm
  271.  
  272. Call with:   no parameters
  273. Returns:     nothing
  274. Uses:        no registers or flags
  275. Example:
  276.  
  277. include asm.inc
  278.  
  279. extrn  snowoff:proc
  280. extrn  getcrt:proc
  281.  
  282. .code
  283.        .
  284.        .
  285.        .
  286.        call   getcrt
  287.        cmp    ax,2             ; ASMLIB doesn't disable snow control
  288.                                ; on MCGA systems
  289.        jne    continue
  290.        call   snowoff          ; MCGA doesn't need snow control
  291. continue:
  292.  
  293.  
  294.        
  295.  
  296. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  297.  
  298. STR2VBUF:    copies a string to video memory buffer, with selected
  299.              color attribute; includes snow control for CGA systems
  300. Source:      str2vbuf.asm
  301.  
  302. Call with:   CX = maximum number of characters to print (will also stop
  303.                   at NUL character)
  304.              DX = 0 to disable snow control
  305.                 = 3DAh to enable CGA snow control
  306.                   (if DX = 3DAh on systems without a color monitor,
  307.                   the computer will jam up solid)
  308.              DS:[SI] points to first character of string
  309.              ES:[DI] points to video buffer
  310.              AH = color attribute
  311.              DF = 0 (clear direction flag with CLD)
  312. Returns:     ES:[DI] points to video buffer following string
  313.              if AL = 0
  314.                 DS:[SI] points to byte following string's NUL terminator
  315.              if AL <> 0
  316.                 DS:[SI] points to next byte in string after the last one
  317.                 printed on the screen
  318. Uses:        AL, CX, DI, SI, flags
  319.  
  320.  
  321.  
  322. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  323.  
  324. TCENTER:     prints a string on the screen, centered horizontally
  325. TNCENTER:    prints CX bytes of a string on the screen, centered horizontally
  326. Source:      tcenter.asm (crtinfo.asm, str2vbuf.asm, strlen.asm)
  327.  
  328. Call with:   DS:[SI] pointing to the string
  329.              DH = row to print the string on
  330.              AH = color attribute
  331.              (tncenter only) CX = number of bytes to print
  332. Returns:     nothing
  333. Uses:        nothing
  334. Supports:    all ASMLIB text modes; includes CGA snow control
  335. Example:
  336.  
  337.      assume  ds:@data
  338.      mov     ax,@data
  339.      mov     ds,ax       ; the string is in DGROUP
  340.  
  341.      lea     si,string   ; DS:[SI] points to the string
  342.      mov     dh,row
  343.      mov     ah,attr     ; color attribute
  344.      call    tcenter     ; center the string on row in DH
  345.  
  346.  
  347.  
  348. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  349.  
  350. TCLEAR:      clear a text-mode screen with specified color attribute
  351. Source:      tclear.asm (crtinfo.asm, a$putw.asm)
  352.  
  353. Call with:   AH = color attribute
  354. Returns:     nothing
  355. Uses:        AL
  356. Supports:    all ASMLIB text modes; includes CGA snow control
  357. Example:     mov    ah,color
  358.              call   tclear
  359.  
  360.  
  361. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  362.  
  363. TCOPY:       copies one page of text-mode video memory to another page
  364. Source:      tcopy.asm (crtinfo.asm, tpage.asm, $herc.asm)
  365.  
  366. Call with:   BH = frompage, BL = topage
  367. Returns:     if CF = 0, all OK
  368.              if CF = 1 and AH = -1, frompage number is out-of-bounds
  369.              if CF = 1 and AL = -1, topage number is out-of-bounds
  370. Uses:        AX, CF
  371. Supports:    all ASMLIB text modes, pages 0 - 15; includes CGA snow control
  372. Example:     mov    bh,0               ; frompage
  373.              mov    bl,1               ; copy from page 0 to page 1
  374.              call   tcopy
  375.              jc     oops               ; oh yuck - an MDA
  376.  
  377.  
  378. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  379.  
  380. TFILL:       fill a text-mode screen with specified character and color
  381. Source:      tclear.asm (crtinfo.asm, a$putw.asm)
  382.  
  383. Call with:   AH = color attribute, AL = fill character
  384. Returns:     nothing
  385. Uses:        nothing
  386. Supports:    all ASMLIB text modes; includes CGA snow control
  387. Example:     mov    ah,color
  388.              mov    al,char              ; AL = character to fill screen
  389.              call   tfill
  390.  
  391.  
  392.  
  393. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  394.  
  395. TGETCHR:     read character and attribute from text screen
  396. Source:      tgetchr.asm
  397.  
  398. Call with:   DH = screen row
  399.              DL = screen column
  400. Returns:     AH = color atttribute
  401.              AL = ASCII character code
  402. Supports:    all ASMLIB text modes; includes CGA snow control
  403. Example:
  404.  
  405. include asm.inc
  406.  
  407. extrn tgetchr:proc
  408.  
  409. .data
  410.  
  411. position label word
  412. column   db 13
  413. row      db 18
  414.  
  415. .code
  416. ; program fragment assumes DS:@data
  417.          .
  418.          .
  419.          .
  420.          mov   dx,position
  421.          call  tgetchr         ; returns with AL = ASCII character code
  422.                                ;  and with AH = color attribute
  423.  
  424.  
  425.  
  426.  
  427. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  428.  
  429. TLOAD:       loads a screen image disk file saved by TSave
  430. Source:      tsave.asm (crtinfo.asm)
  431.  
  432. Call with:   DS:[DX] = address of ASCIIZ filename
  433. Returns:     if CF = 1, AX = MS-DOS file I/O error code
  434.              if CF = 0, no error
  435. Uses:        AX, CF
  436. Supports:    all ASMLIB text modes; no CGA snow control
  437.              see also TSave
  438. Example:
  439.  
  440. extrn tload:proc
  441.  
  442. .data
  443.  
  444. filename  db 'tscreen.bin',0
  445.  
  446. .code
  447.      .
  448.      .
  449.      .
  450.  
  451.      lea   dx,filename
  452.      call  tload
  453.  
  454.  
  455.  
  456.  
  457.  
  458. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  459.  
  460. TPAGE:       changes active page and shows new active page
  461. Source:      tpage.asm (crtinfo.asm, $herc.asm)
  462.  
  463. Call with:   BL = page number
  464.              for ASMLIB subroutines writing directly to video memory.
  465.              See also UseTPage and ShowTPage.  ASMLIB's active page is
  466.              not affected by INT  10h mode changes.
  467.              Page -1 may be used on two-monitor systems, directs ASMLIB
  468.              video output to Monochrome screen (except cursor).
  469. Returns:     AX = error code
  470.              if AX = 0, no error
  471.              if AX = -1, bad page number
  472.              if AX = 1, page may be written to but cannot be shown
  473. Uses:        AX
  474. Supports:    text-mode screens, all row/column configurations
  475. Example:     mov    bl,page
  476.              call   tpage
  477.  
  478.  
  479. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  480.  
  481. TPRINT:      print ASCIIZ string directly to video buffer.
  482.              String must be terminated by a NUL character.
  483. Source:      tprint.asm (crtinfo.asm, str2vbuf.asm)
  484.  
  485. Call with:   DS:[SI] pointing to the string
  486.              DH = screen row, DL = screen column
  487.              AH = color attribute
  488. Returns:     nothing
  489. Uses:        nothing
  490. Supports:    all ASMLIB text modes; includes CGA snow control
  491. Example:     assume  ds:@data
  492.              mov     ax,@data
  493.              mov     ds,ax       ; the string is in DGROUP
  494.  
  495.              lea     si,string   ; DS:[SI] points to the string
  496.              mov     dh,row
  497.              mov     dl,column
  498.              mov     ah,attr     ; color attribute
  499.              call    tprint
  500.  
  501.  
  502.  
  503. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  504.  
  505. TPRINTCE:    prints an ASCIIZ string on the screen at specified position
  506.              and specified color, and clears from the end of the string
  507.              to the right edge of the screen
  508. Source:      tprintce.asm (crtinfo.asm, str2vbuf.asm, a$putw.asm)
  509.  
  510. Call with:   DS:[SI] pointing to the string
  511.              DH = screen row, DL = screen column
  512.              AH = color attribute
  513. Returns:     nothing
  514. Uses:        nothing
  515. Supports:    all ASMLIB text modes; includes CGA snow control
  516. Example:     assume  ds:@data
  517.              mov     ax,@data
  518.              mov     ds,ax       ; the string is in DGROUP
  519.  
  520.              lea     si,string   ; DS:[SI] points to the string
  521.              mov     dh,row
  522.              mov     dl,column
  523.              mov     ah,attr     ; color attribute
  524.              call    tprintce
  525.  
  526.  
  527. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  528.  
  529. TPRINTL:     print ASCIIZ string directly to video buffer, lower case
  530. Source:      tprintl.asm (crtinfo.asm)
  531.  
  532. TPRINTU:     print ASCIIZ string directly to video buffer, upper case
  533. Source:      tprintu.asm (crtinfo.asm)
  534.  
  535.              String must be terminated by a NUL character.  Similar to TPrint,
  536.              but characters a - z are TPrinted as upper case A - Z (TPrintU)
  537.              or characters A - Z are TPrinted as lower case a - z (TPrintL).
  538.              The string itself is not altered.
  539.  
  540. Call with:   DS:[SI] pointing to the string
  541.              DH = screen row, DL = screen column, AH = color attribute
  542.  
  543. Returns:     nothing
  544. Uses:        nothing
  545. Supports:    all ASMLIB text modes; includes CGA snow control
  546. Example:     assume  ds:@data
  547.              mov     ax,@data
  548.              mov     ds,ax       ; the string is in DGROUP
  549.  
  550.              lea     si,string   ; DS:[SI] points to the string
  551.              mov     dh,row
  552.              mov     dl,column
  553.              mov     ah,attr     ; color attribute
  554.              call    tprintu
  555.  
  556. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  557.  
  558. TSAVE:       saves a screen image as a disk file; does not compress the image
  559. Source:      tsave.asm (crtinfo.asm)
  560.  
  561. Call with:   DS:[DX] = address of ASCIIZ filename
  562. Returns:     if CF = 1, AX = MS-DOS file I/O error code
  563.              if CF = 0, no error
  564. Uses:        AX, CF
  565. Supports:    All ASMLIB text modes; no CGA snow control
  566.              see also TLOAD
  567. Example:
  568.  
  569. extrn tsave:proc
  570.  
  571. .data
  572.  
  573. filename  db 'tscreen.bin',0
  574.  
  575. .code
  576.      .
  577.      .
  578.      .
  579.  
  580.      lea   dx,filename
  581.      call  tsave
  582.  
  583.  
  584. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  585.  
  586. UCURSORON:   similar to CursorON, but the underscore cursor is used regardles
  587.              of the state of the INSERT toggle.  See also CursorON.
  588. Source:      cursor.asm (crtinfo.asm)
  589.  
  590. Call with:   DH = row offset from top of screen
  591.              DL = column offset from left side
  592. Returns:     nothing
  593. Uses:        AX
  594. Supports:    text mode, all pages, all row/column configurations
  595. Example:     mov    dh,row
  596.              mov    dl,col
  597.              call   ucursoron
  598.  
  599.  
  600. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  601.  
  602. USETPAGE:    establish ASMLIB's active page
  603. Source:      tpage.asm (crtinfo.asm, $herc.asm)
  604.  
  605. Call with:   BL = page number
  606.              ASMLIB text-mode subroutines can be directed to any video
  607.              page.  ASMLIB's active page is not affected by INT  10h
  608.              mode changes.  UseTPage does not change the page shown
  609.              on the screen.  See also TPage and ShowTPage.
  610.              If newpage = -1, ASMLIB video output is directed to a
  611.              Monochrome screen
  612. Returns:     AX = error code
  613.              if AX = -1, bad page number
  614. Uses:        AX, ES
  615. Supports:    All ASMLIB text modes
  616. Example:     mov     bl,page
  617.              call    usetpage
  618.  
  619.  
  620.  
  621. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  622.  
  623. VSCROLL:     scroll a portion of the screen up or down.
  624. Source:      vscroll.asm (a$wdata.asm, $wcopy.asm, a$putw.asm, $exit.asm)
  625.  
  626. Call with:   DS:[BX] pointing to corners of scroll area
  627.              AH = color attribute, CX = number of rows to scroll
  628.              Scrolls up if CX > 0, scrolls down if CX < 0, clears area
  629.              if CX = 0
  630. Returns:     nothing
  631. Uses:        nothing
  632. Supports:    all ASMLIB text modes; includes CGA snow control
  633. Example:
  634.  
  635. .data
  636.  
  637. wdata        dw     10               ; row0
  638.              dw     10               ; column0
  639.                                      ; (row0, column0) = upper left corner
  640.              dw     20               ; row1
  641.              dw     40               ; column1
  642.                                      ; (row1, column1) = lower right corner
  643. .code
  644.              .
  645.              .
  646.              .
  647.              lea    bx,wdata         ; DS:[BX] points to window coordinates
  648.              mov    ah,color
  649.              mov    cx,3             ; scroll up 3 rows
  650.              call   vscroll
  651.  
  652.  
  653. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  654.  
  655. WCLEAR:      clear a rectangular portion of a text-mode screen
  656. Source:      wclear.asm (a$wdata.asm, crtinfo.asm, a$putw.asm)
  657.  
  658. Call with:   DS:[BX] pointing to box corner data
  659.              AH = color attribute
  660. Returns:     nothing
  661. Uses:        AL, flags
  662. Supports:    all ASMLIB text modes; includes CGA snow control
  663. Example:
  664.  
  665. .data
  666.  
  667. wdata        dw     10               ; row0
  668.              dw     10               ; column0
  669.              dw     20               ; row1
  670.              dw     40               ; column1
  671.  
  672. .code
  673.              .
  674.              .
  675.              .
  676.              lea    bx,wdata         ; DS:[BX] points to window coordinates
  677.              mov    ah,color
  678.              call   wclear           ; clear a box on the screen with corners
  679.                                      ; at (row0, column0), (row1, column0),
  680.                                      ; (row0, column1) and (row1, column1)
  681.  
  682.  
  683.  
  684.  
  685. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  686.  
  687. WFILL:       fill a rectangular protion of a text-mode screen with
  688.              specified character and attribute; variation of WClear
  689. Source:      wclear.asm (a$wdata.asm, crtinfo.asm, a$wclr.asm)
  690.  
  691. Call with:   DS:[BX] pointing to box corner data
  692.              AH = color attribute
  693.              AL = fill character
  694. Returns:     nothing
  695. Uses:        flags
  696. Supports:    all ASMLIB text modes; includes CGA snow control
  697. Example:
  698.  
  699. .data
  700.  
  701. wdata        dw     10               ; row0:    top of fill area
  702.              dw     10               ; column0: left side of fill area
  703.              dw     20               ; row1:    last row of fill area
  704.              dw     40               ; column1: right side of fill area
  705.  
  706. .code
  707.              .
  708.              .
  709.              .
  710.              lea    bx,wdata         ; DS:[BX] points to window coordinates
  711.              mov    ah,color
  712.              mov    al,'■'           ; use ASCII 254 to fill
  713.              call   wfill            ; fill a box on the screen with corners
  714.                                      ; at (row0, column0), (row1, column0),
  715.                                      ; (row0, column1) and (row1, column1)
  716.  
  717.  
  718.  
  719. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  720.  
  721. WFRAME:      draw a box on a text-mode screen
  722. Source:      wframe.asm (a$wdata.asm, a$putw.asm, crtinfo.asm)
  723.  
  724. Call with:   DS:[BX] pointing to box corner data
  725.              AH = color attribute
  726.              AL = box character
  727.              box character is the character associated with an ASCII code
  728.              if AL = 0, a single line is used
  729.              if AL = -1, a double line is drawn
  730. Returns:     if bad window dimensions, CF = 1
  731.              if no problem, CF = 0
  732. Uses:        flags
  733. Supports:    all ASMLIB text modes; includes CGA snow control
  734. Example:
  735.  
  736. .data
  737.  
  738. wdata        dw     10               ; row0
  739.              dw     10               ; column0
  740.              dw     20               ; row1
  741.              dw     40               ; column1
  742.  
  743. .code
  744.              .
  745.              .
  746.              .
  747.              lea    bx,wdata         ; DS:[BX] points to window coordinates
  748.              mov    ah,color
  749.              mov    al,'■'           ; use ASCII 254 for boundary
  750.              call   wframe           ; draw a box on the screen with corners
  751.                                      ; at (row0, column0), (row1, column0),
  752.                                      ; (row0, column1) and (row1, column1)
  753.  
  754.  
  755.  
  756. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  757.  
  758. WSIZE:       calculate the memory required to save a screen window
  759. Source:      wsize.asm
  760.  
  761. Call with:   DS:[BX] pointing to row & column coordinates
  762.              The row and column coordinates define the corners of the
  763.              window.
  764. Returns:     AX = bytes required
  765. Uses:        AX
  766. Supports:    All ASMLIB text modes
  767. Example:     
  768.  
  769. .data
  770.  
  771. wdata        dw     10               ; row0
  772.              dw     10               ; column0
  773.              dw     20               ; row1
  774.              dw     40               ; column1
  775.  
  776. .code
  777.  
  778.              .
  779.              .
  780.              .
  781.              lea    bx,wdata         ; DS:[BX] points to window coordinates
  782.              call   wsize            ; returns AX = bytes needed to save window
  783.              jc     oops
  784.              call   halloc           ; allocate space from near heap
  785.              jc     drat
  786.              
  787.  
  788.  
  789.  
  790. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  791.  
  792. WPAINT:      replace all color attributes in a window of the screen
  793. Source:      wpaint.asm (a$wdata.asm, crtinfo.asm, a$paint.asm, $exit.asm)
  794.  
  795. Call with:   DS:[BX] pointing to window coordinates
  796.              AH = new color attribute
  797. Returns:     nothing
  798. Uses:        nothing; all registers and flags are saved
  799. Supports:    all ASMLIB text modes; includes CGA snow control
  800. Example:
  801.  
  802. .data
  803. wdata        dw     10               ; row0
  804.              dw     10               ; column0
  805.              dw     20               ; row1
  806.              dw     40               ; column1
  807.  
  808. .code
  809.              .
  810.              .
  811.              .
  812.              lea    bx,wdata         ; DS:[BX] points to window coordinates
  813.              mov    ah,color         ; AH = new color attribute
  814.              call   wpaint
  815.  
  816.  
  817.  
  818. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  819.  
  820. WPRINT:      print ASCIIZ string directly to the video buffer in a
  821.              window of screen, with word wrap.  String must be terminated
  822.              by a NUL character.  WPrint clears any portion of the window
  823.              not occupied by the string.
  824. Source:      WPRINT.ASM (crtinfo.asm, str2vbuf.asm, strlen.asm, a$wdata.asm,
  825.                          a$putw.asm)
  826.  
  827. Call with:   DS:[SI] pointing to the string
  828.              DS:[BX] pointing to window corners
  829.              AH = color attribute
  830.              note that the string and the window corner data must be in
  831.              the same segment
  832. Returns:     nothing
  833. Uses:        nothing
  834. Supports:    all ASMLIB text modes; includes CGA snow control
  835. Example:
  836.  
  837. extrn   wframe:proc, wprint:proc
  838.  
  839. .data
  840. wdata   dw 10,10,20,30          ; window corner data: upper left at row 10,
  841.                                 ; column 10; lower right at row 20, column 30
  842. string  db "The quick brown fox jumped over the lazy dog's back",0
  843.  
  844. .code
  845.      assume  ds:@data
  846.      mov     ax,@data
  847.      mov     ds,ax       ; the string is in DGROUP
  848.      lea     si,string   ; DS:[SI] points to the string
  849.      lea     bx,wdata    ; DS:[BX] points to corner data
  850.      mov     ah,12       ; bright red!!
  851.      call    wprint
  852.  
  853.      dec     wdata       ; stretch the window borders a bit
  854.      dec     wdata+2     ; so I can draw a frame around the silly text
  855.      inc     wdata+4
  856.      inc     wdata+6
  857.      mov     al,-1       ; double-line border
  858.      mov     ah,14       ; bright yellow
  859.      call    wframe
  860.  
  861.  
  862. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  863.  
  864. WRECOLOR:    change selected color attributes in a window of the screen
  865. Source:      wrecolor.asm (a$wdata.asm, crtinfo.asm, a$recolr.asm, $exit.asm)
  866.  
  867. Call with:   DS:[BX] pointing to window corner data
  868.              AL = color attribute to be replaced
  869.              AH = new color attribute
  870. Returns:     nothing
  871. Uses:        nothing; all registers and flags are saved
  872. Supports:    all ASMLIB text modes; includes CGA snow control
  873. Example:
  874.  
  875. .data
  876. wdata        dw     10               ; row0
  877.              dw     10               ; column0
  878.              dw     20               ; row1
  879.              dw     40               ; column1
  880.  
  881. .code
  882.              .
  883.              .
  884.              .
  885.              lea    bx,wdata         ; DS:[BX] points to window coordinates
  886.              mov    ah,newcolor      ; AH = new color attribute
  887.              mov    al,oldcolor      ; AL = color to be replaced
  888.              call   wrecolor         ; replace oldcolor with newcolor
  889.                                      ; within the window
  890.  
  891.  
  892. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  893.  
  894. WRESTORE:    restore a portion of a text-mode screen from a buffer
  895. WSAVE:       save a portion of a text-mode screen to a buffer
  896.              (handy when using pop-up windows on the screen)
  897. Source:      wsave.asm (a$wdata.asm, crtinfo.asm, $wcopy.asm)
  898.  
  899. Call with:   ES:[DI] pointing to memory buffer
  900.              DS:[BX] pointing to corner data
  901.              The memory buffer must be sized to hold the entire window.
  902.              See wsize.
  903. Returns:     nothing
  904. Uses:        nothing
  905. Supports:    all ASMLIB text modes; includes CGA snow control
  906. Example:
  907.  
  908. .data
  909.  
  910. wdata    dw 10               ; row0
  911.          dw 10               ; column0
  912.          dw 20               ; row1
  913.          dw 40               ; column1
  914. buffer   dw 2000h            ; oversize
  915.  
  916. .code
  917.  
  918.          .
  919.          .
  920.          .
  921. ; save a part of the screen
  922.          mov    ax,@data
  923.          mov    es,ax
  924.          mov    ds,ax
  925.         assume  ds:@data, es:@data
  926.          lea    bx,wdata         ; DS:[BX] points to window coordinates
  927.          lea    di,es:buffer     ; point to buffer
  928.          call   wsave
  929.          .
  930.          .
  931.          .
  932. ; sometime later ...
  933. ; restore the window saved earlier
  934.          mov    ax,@data
  935.          mov    es,ax
  936.          mov    ds,ax
  937.         assume  ds:@data, es:@data
  938.          lea    bx,wdata         ; DS:[BX] points to window coordinates
  939.          lea    di,es:buffer     ; point to buffer
  940.          call   wrestore
  941.