Libvt - A VT52/VT100/ANSI display library for c68 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Why ~~~ Like it or not, the MSDOS world is a great source of public domain 'C' language software that can often be easily ported to run on other platforms, such as the QDOS based machines. One of the problems you encounter with programs from the MSDOS world is that many of the programs use ANSI escape sequences to control the screen display. For example, "$[2J" (where $ represents the escape character, ASCII 27, 1b hex), will clear the screen, "$[10;10H" will position the cursor at position row 10, column 10 (note ANSI co-ordinates start at 1,1). There are many other escape sequences that change colours, underline etc, etc. It is a real pain to have to go through a large, complex program and find all instances of ANSI escape sequences and convert them to QL specific functions such as sd_clear, sd_pos etc. If the program can also display disk files that may contain ANSI codes, then the problem becomes horrific. With libvt, the problems disappear, just use standard C output functions like printf, puts etc with the original ANSI codes, and your QL screen behaves (almost) like a PC. How ~~~ To use libvt_a in your programs, you need to do three things. 1. #include "ansicondef.h" in a module. This defines some useful manifest constants and a globally visable typedef'ed structure ANSICONDEF __ANSICONF__. This structure defines two global fields, the emulation which may take the values (VT52, VT100, ANSI1, ANSI2, ANSI3, ANSI4), and the way the program handles the CSI character (ASCII 155, hex 9B). The defaults are: __ANSICONF__.emulation = VT100; __ANSICONF__.CSI = 0; A value of zero means that CSI is taken as the ANSI lead-in sequence (ESC [). If CSI is non-zero then CSI is a normal eight bit character. 2. Define the default conwrite() routine as ANSI_conwrite. Do this by including the line: long (*_conwrite)() = ANSI_conwrite; 3. Link your program with libvt_a. Add -lvt to the your ld command line. ANSI Modes ~~~~~~~~~~ The ANSI emulation (ANSI1 - ANSI4) define how libvt handles ANSI colours. The ANSI standard specifies support for eight colours (BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN and WHITE. In mode 4, the QL can only display BLACK, RED, GREEN and WHITE. If you select ANSI1 mode, the colours YELLOW, BLUE, CYAN and MAGENTA are simulated using stipple patterns to give a muddy yellow, pale grey, pale green and darker red. The downside is that if text is written over a stippled background (or text is written in a stippled colour), then it is difficult to read. The ANSI2 emulation just maps the missing colours to WHITE, BLACK, READ and GREEN, which means that BLUE on a BLACK background comes out as all BLACK, which is even less satisfactory. A number of the ANSI screens contain white text on green background, which on my MicroVitec monitor is difficult to read. ANSI1 and ANSI2 ignore the ANSI bold ANSI3 and ANSI4 support ANSI bold, emulating a sixteen colour ANSI display. Due the the hardware palette of the QL (four colours), it is difficult to select sufficient stipple patterns that work under all circumstances. ANSI3 has an additional 8 stipple patterns, but these are frequently difficult to read when text is involved (text constructed from ANSI graphics especially). ANSI4 attempts to use a QL base colour (red, green, white, black) for ANSI bold when ever possible. I find ANSI4 is the most statisfactory compromise for the majority of ANSI screens. Screen Size ~~~~~~~~~~~ Most displays using ANSI (or VT52,VT100), expect an 80 character by 24 (or 25) line display. You may get unpredicatble results using smaller displays. libvt does not check for a suitable size. Other Info ~~~~~~~~~~ libvt is about 13.5 Kb, while ANSI.SYS on a PC is about 9Kb, so is libvt wanton in its use of memory ? I think not, as libvt includes almost 2K of alien screen fonts (the 128 character 8 bit ANSI set, thirty one ANSI 'control' characters and thirty one DEC line drawing graphics characters. In addition libvt gives VT52 and VT100 emulations and a complex mapping of 16 ANSI colours onto four QL colours. It seems like a reasonable deal to me. The additional character sets are defined as exernal in "ansicondef.h". These are standard QL screen fonts that may be used as arguments to sd_fount (sic). Bugs ~~~~ I'm not saying whose, of course, and really this section should be entitled 'features'. If you use VT100 emulation with VT100 scrolling regions, then libvt redefines the output window to be the size of the scrolling region when it has to scroll that region. This is a cop out that makes it relatively easy to program. If you need to do this with the Pointer Enviroment you should ensure that the window's outline has been set before any scrolling regions are defined, otherwise the PE may 'reclaim' some of your window when the scrolling region is sd_wdef'ed. You can set the outline by: a. Write your program as a PE application using libqptr. b. Use the c68 default (*_consetup)() procedure. c. Use the (undocumented) c68 iop_outl() procedure as shown below. You don't need to #include qptr.h or link with -lqptr. You can ignore any warning about type mismatch in paramter 6 in iop_outl. iop_outl(getchid(1), -1, 0, 0, 0, &_condetails.width); The ANSIView example below uses technique (c). Example Program ~~~~~~~~~~~~~~~ libvt is supplied with an example program that shows just how easy it is to use. ANSIView is a ANSI (or VT100/VT52) file viewer. It takes multiple arguments. ex ANSIView;'-mn files' where -mn is the emulation n: 0=VT52, 1=VT100, 2=ANSI1 ... 5=ANSI4 files may be a single file, a list or wildcards. for example, to view all *_ans files on flp2_ with ANSI4 emulation ex ANSIView;'-m5 flp2_*_ans' to view the QualSoft VT100 demo (VT100 emulation !!) ex ANSIView;'-m1 vt100_test' You can actually do this in one command, as ANSIView will change emulation 'on the fly'. The -m parameter only applies until a new one is found. ex ANSIView;'-m1 flp2_vt100_test -m5 flp2_*_ans' The makefile is designed for use on my AmigaDos c68 'cross-compiler' for the QL, you will have to make some trivial changes to use this on a QDOS system. This is 'left as an exercise for the reader' :-). *** DJW *** The Makefile provided on the C68 disks works with QDOS Further Documentation ~~~~~~~~~~~~~~~~~~~~~ libvt is (as you may have guessed) based on the VT/ANSI emulation in the comms programs QeM and QTPI. A document describing all the VT/ANSI escape sequences recognised by these programs is "QeM-ANSI_txt" and should be available from the 4th Dimension BBS and other high class repositories of QL information. libvt supports all the codes described in this document with the exception of the Device Status Report (DSR) codes, which are not relevent to libvt. The Small Print ~~~~~~~~~~~~~~~ libvt is FREEWARE. This means that it may be freely distributed without charge, under the following conditions. 1. The copyright holder is Jonathan R Hudson. 2. The package shall be distributed complete (libvt_a, ansiview_c, ansiview and libvt_txt). 3. libvt may be included in user group and public domain libraries provided: a. Any fee charged is 'reasonable'; it may cover the cost of a blank disk, copying and mailing fees. You may not profit from distributing libvt. b. The library does not claim ownership of the software or copyright. c. The library does not place any restriction on the further distribution of the software. 4. libvt may be included in any compiled commercial program, as long as an acknowledgement is made. Permission is specifically granted to Dave Walker to include this library in the c68 QL 'C' compiler package. libvt is compiled with the excellent c68 compiler (or at least by my AmigaDOS 'cross-compiler' variant thereof). Versions ~~~~~~~~ 0.01 Initial Release 0.02 Fixed bug in 8 bit ANSI mode (CSI as control character). Author ~~~~~~ Jonathan Hudson, PO Box 2272, Ruwi 112, Sultanate of Oman. Tel/Fax: +968 699407