# The T3X Extensions

## Release 1

### (4th revised issue)

Copyright © 1996-2000 Nils M. Holm
mail: nmh@t3x.org
home: http://www.t3x.org/

# Table Of Contents

- 1. The VIO Extension
- 2. The Graphics Extension
- 3. License

# 1. The VIO Extension

The VIO extension provides raw access to the user's terminal screen and keyboard.

Procedure | Slot | Description
--- | --- | ---
`VIO_CLEAR()` | 36 | Clear the content of the terminal screen by filling it with blank characters in the currently selected background color. Return nothing.
`VIO_CLREOL()` | 37 | Clear the current line from the position of the logical cursor to the end of the line by replacing characters with blanks. Use the currently selected background color. Return nothing.
`VIO_COLOR(CM) (*) Number CM` | 38 | Select new foreground and background colors. The color mask CM consists of seven bits with the following meanings:

`Rf` | `Gf` | `Bf` | `In` | `Rb` | `Gb` | `Bb`

R,G,B are flags indicating whether the Red, Green, and Blue portion of the color value is turned on or off. 'f' indicates foreground and 'b' indicates background. `In' controls the intensity of the foreground color (1=high,0=low). VIO_COLOR() returns nothing.
The interpretation of the color codes depends on the terminal type detected by VIO_INIT(). When the terminal can display color, ANSI color sequences are used. On monochrome TTYs, normal text mode is used, if the selected background color is black, and otherwise standout mode is used.
`VIO_END()` | 31 | Shut down the VIO package. Basically, put the user's terminal back to a known state so that the terminal will not become inaccessible after program termination. VIO_END() returns nothing.
`VIO_GETC()` | 40 | Read a single key from the user's terminal and return its ASCII code or extended keycode (**).
`VIO_INDEX(T,B) Number T,B` | 42 | Scroll the screen region specified by T (top line) and B (bottom line) up by one line. The bottom line will be filled with blank characters using the currently selected background color. VIO_INDEX() returns nothing.
`VIO_INIT()` | 30 | Initialize the VIO extension. Return nothing. On failure, print a message and abort the calling program. The terminal will be put into raw mode on systems which distinguish TTY modes. VIO_INIT() must be called before any other routines of the VIO system can be used.
VIO_INIT() also determines the color capability of the connected terminal. On Unix systems, the $ANSICOLOR variable can be used to enable or disable color explicitly. If $ANSICOLOR has one of the values {no,No,NO}, color is disabled, and if it has any other value (including none), color is enabled. If the variable is undefined, color is only used, if the terminal name ($TERM) contains the substring "color".
`VIO_MOVE(X,Y) Number X,Y` | 41 | Move the logical cursor to the position specified by the coordinates X and Y (row Y, column X). The upper left corner has the coordinates (0,0). Return nothing.
`VIO_PUTC(C) Number C` | 34 | Write the character C to the position pointed to by the logical cursor using the currently selected colors. If the right border of the screen has been reached, wrap around to the next line. If the bottom of the screen has been reached, scroll up the screen content by one line. Return C.
`VIO_PUTS(P) Pstring P` | 35 | Write the packed string P to the terminal screen using the currently selected colors. Each character will be output as if it had been written by VIO_PUTC(), but VIO_PUTS() is more efficient on most systems. VIO_PUTS() returns nothing.
`VIO_QUERY()` | 39 | Check for terminal input. If VIO_QUERY() returns zero, a subsequent call to VIO_GETC() will block. If it returns a non-zero value, a call of VIO_GETC() will return immediately.
`VIO_REINIT()` | 32 | Reinitialize the VIO extension. Simply switch the terminal to raw mode (where necessary). Return nothing.
`VIO_REVIND(T,B) Number T,B` | 42 | Scroll the screen region specified by T (top line) and B (bottom line) down by one line. The top line will be filled with blank characters using the currently selected background color. VIO_REVIND() returns nothing.
`VIO_SYNC()` | 33 | Synchronize the cursors by moving the hardware cursor to the position of the logical cursor. The logical cursor is the position where the next output operation will take place while the hardware cursor is the one which is visible to the user. VIO_SYNC() does not return any meaningful value.

(*) The following color constants are available:

    F_BLACK, F_BLUE, F_GREEN, F_CYAN, F_MAGENTA,
    F_YELLOW, F_GREY, F_BRIGHT
    B_BLACK, B_BLUE, B_GREEN, B_CYAN, B_MAGENTA,
    B_YELLOW, B_GREY.

`F_...` denotes a foreground and `B_...` denotes a background color. Foreground and background colors may be combined using a bitwise OR.

(**) Special (non-ASCII) keys will return codes between 256 and 512. The following constants are available:

    K_HOME, K_LEFT, K_RGHT, K_BKSP, K_DEL, K_KILL (Rubout),
    K_INS, K_UP, K_DOWN, K_ESC, K_NEXT, K_PREV, K_F1...K_F10.

# 2. The Graphics Extension

The graphics extension provides access to a virtual, vector-based black and white graphics device which will be mapped to the user's terminal screen. The virtual graphics device has a layout with the origin at the center of the screen and a resolution of about 32000 x 24000 points (and consequently, an aspect ratio of 4/3). This layout will be mapped to the actual hardware layout and resolution by the graphics driver.

The layout is illustrated in the following figure:

    +---------------------------------------+
    | \                                   / |
    |  -16000,-12000          16000,-12000  |
    |                                       |
    |                                       |
    |                  0,0                  |
    |                   +                   |
    |                 Origin                |
    |                                       |
    |                                       |
    |  -16000,12000            16000,12000  |
    | /                                   \ |
    +---------------------------------------+

Besides access to the virtual graphics device, the graphics extension also provides access to th user's keyboard and pointing device (mouse, trackball, touchpad, etc).

Procedure | Slot | Description
--- | --- | ---
`G_BOX(X,Y,DX,DY,MODE) Number X,Y,DX,DY Number MODE` | 57 | Draw a solid box with its upper left corner at (X,Y) and its lower right corner at (DX,DY). Use the specified MODE (*) for drawing the box.
`G_CLEAR(MODE) Number MODE` | 54 | Clear the graphics device using the specified mode (*).
`G_COPYFONT(A,B) Vector A,B` | 64 | Copy the vector font structure which has been loaded during initialization into the buffer B. A will be initialized with indices into the font buffer so that each A[I] represents the font information associated with the I'th character in the ASCII alphabet.
The information contained in each `@B::A[I]` for I={0,...,127} is suitable for passing it to G_PUTV().
When a null argument is supplied for either A or B, no data will be transferred by the procedure, but in any case, the number of bytes required to store the font information in B will be returned.
`G_END()` | 51 | Shut down the graphics extension. If a new window has been opened by G_INIT(), this routine closes it. If the TTY mode had to be changed when initializing the graphics routines, G_END() restores it. No meaningful value is returned.
`G_EVENT(E,B) Event E Number B` | 52 | Wait for an event to occur or poll the event handler (*4).B is the `blocking' flag. If B=0, G_EVENT() polls the event handler and returns immediately. In this case, the return value indicates whether something has happened: 0=no event, -1=an event took place. If B\=0, the routine waits until an event happens. In this case, of course, it returns always -1. In any case, G_EVENT() fills the event structure E which has the following layout:
`STRUCT event = e_x, e_y, e_buttons, e_key;`
The members E_X and E_Y which contain the current position of the mouse cursor will always be updated, even if no event occured. E_BUTTONS holds a bitmask indicating whether buttons on the pointing device have been pressed:
`1=button#1, 2=button#2, 4=button#3`.
E_KEY holds the ASCII value of the key pressed, if any.
B=1 implies G_SYNC().
`G_FONTSIZE(SC,V) Number SC Vector V[2]` | 62 | Examine the number of points a character will occupy on the virtual graphics device using a given scaling factor. SC is the desired scale. V is a vector of the length 2. The size of a character in the X (V[0]) and Y (V[1]) direction will be stored in this vector when the procedure returns. These values can be used to position characters on the display screen. For example,
`32000 / V[0]`
gives the number of columns and
`24000 / V[1]`
gives the number of rows available for text output.
G_FONTSIZE() returns nothing.
`G_INIT()` | 50 | Initialize the graphics extension. Return nothing. Initializing the extension includes the following steps: On systems where applications usually create new windows (like X11), a new window is created and cleared with the default background color (GCLEAR). On systems where applications run in the same window as the command shell (like Plan9 and DOS), only the window is cleared.
G_INIT() also initializes the pointing device where necessary.
Finally, G_INIT() attempts to load the `system' font. It searches the file `system.vf' first in the current directory and then in a path which has been configured when the graphics package has been compiled.
When either the hardware graphics device could not be accessed, or no pointing device is found, G_INIT() prints a message and terminates the calling program.
`G_LINE(X,Y,DX,DY,MODE) Number X,Y,DX,DY Number MODE` | 56 | Draw a line segment from the origin (X,Y) up to and including the position (DX,DY). Draw the line segment using the specified MODE (*).
`G_POINT(X,Y,MODE) Number X,Y Number MODE` | 55 | Place a single point at the virtual position specified by the coordinates X and Y. Use mode MODE (*) for drawing the point.
`G_PUTC(X,Y,SC,M,C) Number X,Y Number SC,M Number C` | 60 | Draw the printable ASCII character C with its lower left edge at position (X,Y) in mode M. (*) G_PUTC() uses the vector font stored in the file `system.vf' to draw the character C. (**) Because of their vector structure, the same amount of characters always fits in the display window, no matter what size it has.
SC gives the scaling factor for drawing the vectorized characters. It must be >=1. When SC=1, all characters are displayed in their original size. When SC=N (N>1), the size of the character will be increased by the factor N. Unprintable characters will display as blanks. G_PUTC() returns nothing.
`G_PUTS(X,Y,SC,M,P) Number X,Y Number SC,M Pstring P` | 61 | Draw the packed string P by sending each character to G_PUTC(). The spacing used to separate the single characters in the string is taken from the vector font file. When a string extends past the right border or the top of the screen, it will be clipped. See also G_PUTC().
`G_PUTV(X,Y,SC,M,B) Number X,Y Number SC,M Bytevector B` | 63 | G_PUTV() is a generalization of G_PUTC(). It draws the figure which is stored in the byte vector B starting at position (X,Y) using the given MODE (*) and scaling factor. The format of the figure is as follows: The first byte of B contains the number of bytes (N) describing the vector image itself. The subsequent N bytes contain the vectors the figure consists of. A bit map is used to represent each vector:

`P` | `D` | `D` | `D` | `L` | `L` | `L` | `L`

P is the pen position (0=up, 1=down).
D is the direction (*3).
L is the length of the vector (0...15).
`G_RESHAPED()` | 59 | Return a flag that indicates whether the window the graphics device is mapped to has been moved or reshaped since the last call to G_INIT() or G_RESHAPED(). When this procedure returns a non- zero value, the content of the window may not reflect the actual content of the virtual graphics device and therefore should be redrawn. When a size change has occured, G_RESHAPED() recomputes the scale of the loaded system font and the scaling factor used to translate virtual point addresses into hardware addresses.
`G_SYNC()` | 58 | On systems which cache graphics operations, commit all pending requests. Thereby, the contents of the virtual graphics device and the hardware screen get synchronized. G_SYNC() does not return any meaningful value.
`G_WAIT(MS) Number MS` | 53 | Sleep (idle) for at least MS milliseconds.

(*) The following modes are available for drawing:

Mode | Description
--- | ---
`GCLEAR` | Use the background color.
`GSET` | Use the foreground color.
`GOR` | OR the foreground color with each background pixel. Since the graphics extension is a monochrome system, this is the same as GSET.
`GXOR` | XOR the foreground color with each background pixel. (Revert the color of each pixel touched by the drawn figure). NOTE: Using this mode when drawing vector figures will lead to strange results, because the connections of each two line segments will be drawn twice.

(**) The default font may be changed by placing a vector font file called `system.vf' in the directory the graphics application is started from. See also G_INIT().

(*3) The direction bits will be interpreted as follows:

          0
      7   |   1
        \ | /
    6 ---- ---- 2
        / | \
      5   |   3
          4

(*4) When G_EVENT() is called with the blocking flag set, the following events will cause it to return:

- Pointer button presses
- Pointer button releases
- Key presses
- Reshape events (window moves or resizes).

# 3. License

This document is part of the T3X compiler package which is subject to the following terms.

T3X -- A Compiler for the Procedural Language T, version 3X
Copyright (C) 1996-2000 Nils M. Holm. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.