home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / CPM / PROGRAMS / BKGRONDR / BG2WYSE.LBR / BGSCREEN.DZC / BGSCREEN.DOC
Text File  |  2000-06-30  |  12KB  |  298 lines
  1. bgscreen.doc    March 9, 1987    bridger mitchell, Plu*Perfect Systems
  2.  
  3.  
  4. Several BackGrounder-ii users have asked for more explanation of the
  5. BGii screendrivers.  So...
  6.  
  7. These are rough notes for experienced assembly-language programmers who
  8. wish to understand and write custom screendriver and functionkey
  9. driver BGii modules.  They should be read in conjunction with the
  10. source code files.
  11.  
  12. This is definitely not a cookbook.   Users without considerable assembly-
  13. language programming experience and a good knowledge of video terminal
  14. characteristics will be over their heads.  
  15.  
  16. The drivers were written in approximately this order: Kaypro '84,
  17. Kaypro '83, Heath 19, Wyse 50, with iterative improvements and
  18. fixes and more comments as time passed.  Hal Bower added many
  19. helpful comments in the Heath 19 code.  Keven Belles, Bruce Morgen
  20. and I developed the Wyse/TVI driver.
  21.  
  22. You'll probably want to refer mostly to the H19 and Wyse files. 
  23. However, each driver has unique features, some of which may be
  24. applicable to your terminal.  The two Kaypro source files include
  25. conditional debugging routines that you may find worth converting
  26. to Zilog mnemonics.
  27.  
  28.  
  29. Screendrivers are complicated, and terminals are notoriously ill
  30. documented.  It takes several major rounds of testing to get
  31. everything working smoothly.  If you tackle a new type of
  32. terminal, do share your efforts!  However, please try to arrange
  33. controlled testing with one or two other users before posting your
  34. code.  And let us know, at the Plu*Perfect Systems BBS, 714-659-4432.
  35.  
  36.  
  37.  
  38.               NOTES FOR CUSTOMIZING A BGii SCREENDRIVER.
  39.  
  40.  
  41. To implement all of BackGrounder's screen-related features, BGii needs
  42. a screen driver that can:
  43.  
  44.     determine the cursor location on the screen,
  45.     read the entire screen, including attributes.
  46.  
  47. There are several types of "terminals":
  48.  
  49.    video-mapped memory screens
  50.         video ram accessible in banked memory
  51.         video ram accessed through video controller
  52.  
  53.    terminals
  54.         transmit screen region
  55.         transmit character at the cursor
  56.     multiple screen page memory
  57.  
  58. The prototype code illustrates several variations:
  59.  
  60.         Kaypro '83: video ram in banked memory, no transmit-cursor command
  61.         Kaypro '84: video accessed thru controller, cursor indirectly
  62.                     determined from commands and registers
  63.         Heath 19:   transmit screen region commands with attribute
  64.                     codes embedded in stream
  65.     Wyse 50:    transmit-screen-page command.  No transmittable attributes
  66.             or modes.  Turning on an attribute at the cursor makes
  67.             it effective for the rest of the line, or until the
  68.             attribute field is terminated.
  69.         
  70.  
  71. A very smart terminal may have several switchable pages of screen
  72. memory.  If the terminal can be caused to copy its current screen to a
  73. designated page and to switch pages in response to escape sequences,
  74. most of the screen save/restore work can be done by the terminal itself
  75. as a parallel process.  This degree of intelligence could also be
  76. included in a terminal emulation program, for example when a computer is
  77. used as a terminal for another host that is running BGii.
  78.  
  79. BGii calls the screendriver entry points with a flags byte in 
  80. register A.  If A, bit 1 is set, the  upper task is in context;
  81. otherwise, the lower task.
  82.  
  83.  
  84. The code has been kept in two sections: a "generic" part that should
  85. apply to almost any terminal, and a "specific" part that must be
  86. customized to the features of the particular terminal. The driver runs
  87. at 4000H (configurable) and interfaces to BGii through a jump table.
  88. (These labeled parts are nearly, but not entirely correct descriptions;
  89. at a couple of spots "generic" code is indeed terminal-dependent, so
  90. read it all.) 
  91.  
  92. The major screendriver functions are summarized here.  For details,
  93. study the prototype code.
  94.  
  95. Screen-save is the most fundamental operation.  It, and screen restore,
  96. should be developed and debugged first, with simple RETurn stubs for
  97. the other functions.  Initial testing with a stand-alone module,
  98. running under a symbolic z80 debugger, is very helpful (see comments
  99. in the Kaypro code) -- the screen image can be checked in the memory buffer.
  100.  
  101. There are several basic decisions to be made:
  102.     how to find the cursor
  103.     how to read the screen characters
  104.     how to read the screen attributes
  105.     what data structure to use to store the characters and attributes
  106.  
  107. Cursor:  If the terminal has a report-cursor-position, that part is easy.
  108. Send the required esc. sequence, and call conin to get the data.
  109. If not, the Kaypro '83 driver trick can be used:  read the screen,
  110. send a character, read the screen again, and find the changed location.
  111. (Yes, the code handles the "unlucky" case of the test character happening
  112. to be what's at that spot on the screen!).  Avoid using any bios-specific
  113. addresses if at all possible, to keep the driver portable across
  114. different bios versions for the same hardware.
  115.  
  116. Reading the screen:  If the terminal has transmit-page, use that. 
  117. Send the esc. command to transmit the page, then call conin
  118. repeatedly and store each received char. in the ram buffer.  You
  119. have to know when the page is finished  -- either the terminal
  120. will send a special end-of-page character, or you must keep
  121. count.  Some terminals send special end-of-line characters also.
  122.  
  123. If there's no transmit-page, can you access the video memory directly?
  124. If so, you read that memory; you need to know exactly the data structure
  125. it uses (see Kaypro '83).  If you can't,  you may be able to get to
  126. it indirectly through the video controller (Kaypro '84).
  127.  
  128. Attributes:  Some terminals send the attributes embedded in the transmitted
  129. page stream (Heath 19).  Video-accessible memory can have the attributes
  130. in a separate data structure, or just use the hi bit (if only reverse video).
  131. And some terminals don't provide the host with access to the attributes.
  132.  
  133. The Wyse50/TeleVideo driver illustrates a defect in the terminal, or
  134. at least one in the documentation:  at this writing, we haven't been
  135. able to determine how to get those terminals to unambiguously transmit
  136. their screen attributes (apart from "stand in/standout", which is
  137. half-intensity).
  138.  
  139. Furthermore, those terminals do not transmit screen cells
  140. containing nuls, making it impossible to accurately restore lines
  141. that were cleared to nuls, rather than cleared to spaces.  Hence,
  142. ALL TERMCAPS AND PROGRAMS WITH VIDEO CONTROL SEQUENCES SHOULD BE
  143. SET TO CLEAR SCREEN, CLEAR LINE, ETC. WITH *SPACES*, NOT WITH
  144. NULS.
  145.  
  146. Storing the screen:  The data structure you choose is affected by how
  147. the terminal supplies the characters and attributes, how best to
  148. transmit them back for a screen redraw, and the need to retrieve
  149. a portion of the screen from that structure for the CUT command.
  150.  
  151. Jump tables:  The external routines save only the registers shown
  152. in the comments.  The full specification of the internal screendriver
  153. routines appears in comments at the head of each routine.
  154.  
  155.  
  156. Notes on specific major routines follow:
  157.  
  158. SCREEN-SAVE:
  159.  
  160. find the cursor position
  161.         if available, use transmit-cursor-position
  162.         else  read entire screen, write signature character,
  163.               read screen again until signature found
  164.  
  165. read entire screen:
  166.         if necessary, home cursor or put it at lower right corner,
  167.         as terminal requires.
  168.         transmit character(s) from screen
  169.         transmit attribute(s) from screen
  170.       some terminals embed attributes in the transmitted stream (heath 19)
  171.         if needed, repeat for 25th(status) line
  172.     
  173.  
  174. SCREEN-RESTORE:
  175.  
  176. if necessary, home cursor
  177. clear attributes
  178. write entire saved screen, including attributes
  179. set cursor to saved position
  180.  
  181.  
  182. CUT-REGION:
  183.  
  184. The BGii command CUT first saves the current screen, then
  185. calls the cut-region code.  This code enables the user to
  186. move the cursor around the screen to mark the upper-left and
  187. lower-right corners of the rectangular region to be cut.
  188.  
  189. It then finds that region of characters in the driver's memory
  190. of the screen, and repeatedly calls a BGii routine to transmit
  191. the region to BGii for safekeeping in the cut buffer.
  192.  
  193. edit keystrokes:
  194.         allow cursor movement, until
  195.         X or x = set 1st mark
  196.         then:
  197.             allow only cursor right, cursor down,
  198.         (H19 allows up, left too)
  199.             but prevent going off screen, or scrolling
  200.           lower-right character of screen requires special attention
  201.           if terminal is in wrap/scroll mode.
  202.             Highlight or blink the marked region as it grows
  203.             until:
  204.             X or x or CR = set 2nd mark
  205.  
  206. write cut region to BGii:
  207.         calculate byte count, number rows, number columns
  208.         send each char in row
  209.         add CR at end of row
  210.  
  211.  
  212. JOT:
  213.  
  214. The JOT command uses the terminal's screen memory as the 'jotpad'.
  215. Thus, it's important to keep the screen from scrolling.  Editing
  216. uses whatever control-characters and ESCape sequences
  217. the terminal/video driver has, plus the wordstar diamond if
  218. there's enough room for that code in the driver.
  219.  
  220. BGii will save the screen when the JOT command terminates with
  221. a <SUSPEND> keypress.  The screendriver JOT code should therefore:
  222.  
  223. clear screen
  224. display 2-line summary of editing command
  225. edit entered keystrokes:
  226.  
  227.         convert CR to CR,LF
  228.         convert DEL to BS,SPACE,BS
  229.         on Control-P, call paste-region (below)
  230.         send anything else to screen
  231.     prevent scrolling
  232.  
  233. paste-region into jotpad:
  234.  
  235. This keypress, while JOT is active, fetches the last-cut
  236. region from elsewhere in BGii and sends it, with suitable
  237. clipping and editing, to the terminal.
  238.  
  239.         get bytecount, rows, cols from BGii's last cut-region
  240.         get 1st row, put on screen at cursor
  241.         get next row, put vertically below cursor,...
  242.         etc.
  243.         prevent going off screen, or scrolling
  244.       lower-right character of screen requires special attention
  245.       if terminal is in wrap/scroll mode.
  246.  
  247.  
  248.  
  249.  
  250.          NOTES FOR CUSTOMIZING A FUNCTION-KEY DRIVER
  251.  
  252. The driver consists of:
  253.  
  254.     an identification sector
  255.     2 sectors of function key codes and labels:
  256.     up to 4 sectors of code and initialized data to:
  257.  
  258.        initialize and deinitialize the terminal's function keys
  259.        "shift" the function keys to sent single 8-bit codes
  260.        "unshift" the keys to send their normal codes/strings
  261.        save the current mode (shift or unshift)
  262.        restore the saved mode
  263.  
  264. As regards function keys, there are two types of terminals, those that:
  265.  
  266.     -  have a ram table of key values in the bios (e.g. Kaypro)
  267.     -  change modes in response to ESCape sequences (e.g. Heath 19)
  268.  
  269. The disk includes source code for one driver of each type.  In most
  270. cases only limited modifications will be needed to the code.  In
  271. addition, the table of key values and identifying labels will
  272. need to be adjusted to fit the particular terminal.
  273.  
  274. The code should be assembled with an absolute address of 3e80h for
  275. the identification sector (see examples).  Load it into memory with
  276. DDT and move 3e80 .... to 100h.  Then SAVE N filename.FNK.
  277.  
  278. If the terminal cannot be configured to send a single 8-bit character
  279. ("native mode") when a function key is pressed, BackGrounder cannot
  280. distinguish the function keypress from a series of single keypresses
  281. that send the same codes from the main keyboard.  Some terminals do not
  282. provide a native mode and always send ESC plus one or more characters. 
  283. In this case it may be possible to modify the BIOS  console input
  284. routine to convert these keys to a native mode, as follows:
  285.     
  286.     get char
  287.     if char is ESC
  288.         wait for 1 char time at current baud rate
  289.         if next char is ready, get it, set bit 7, return that.
  290.         else return ESC, and return the char on next call
  291.  
  292. Because the timing routine must be specific to the system and
  293. be cognizant of the interrupt structure, it is not practical to
  294. include this type of routine in BGii itself.
  295.  
  296. (end of bgscreen.doc March 9, 1987)
  297.  for
  298. the id