GSXTEST 2                                             John Elliott, 2025-08-29 
==============================================================================

  GSXTEST is a program intended to help with GSX driver development. It 
produces a variety of test patterns with the aim of exercising different 
code paths in a typical GSX driver.

  In conception it is similar to my earlier VTEST (for GEM) and GSXTEST 1 
(for GSX) but shares no code with them as it is written in 8080 assembly 
language rather than C.

  The syntax is:

	GSXTEST {devicenumber}

  If the device number is omitted, device 1 is assumed.

  Once loaded, GSXTEST displays a menu listing test groups.

In general
==========
  GSXTEST will usually start by trying to clear the screen to a pattern of 
four quadrants. On a mono display these will be two black, two white; on a 
colour display these ought to be (clockwise from top left) green, blue, red, 
and black, though these may vary on a device with limited colour support. If a 
device doesn't have filled polygon support, the quadrants should at least
be drawn as hollow boxes.

  Test outputs will then appear superimposed on this background.

  It is possible to disable background drawing by using the B option from 
the main menu. This may be helpful for testing drivers that don't implement
write modes other than 'replace' (for example, the HP7470 plotter) or that
have nonstandard implementations (for example, the BBC Micro display drivers).

Cell Array tests
================
  Cell array functionality is very rarely implemented in GSX drivers and so
I haven't been able to check these tests very widely (or at all, in some 
cases).

1. Draw cell array
------------------
  This draws the same image (a smiling face) 64 times, in the four different
write modes supported by GSX. If the driver doesn't support cell arrays, it
should at least draw 64 rectangles in the current line colour.

2. Read cell array
------------------
  This draws the same 'face' image as above, then tries to read it back and
repaint it. The two resulting images should be identical. In practice I 
haven't found any driver which implements this function so you will probably
get an outline or a solid rectangle.

Colour tests
============

  On a monochrome device, these will most likely display the message "No
colour mapping". On a colour display, they should operate at least minimally.

1. Default colours
------------------
  This displays the first 16 colours and their RGB values. At startup, a GSX
driver should map colours as:

	0 = Black
	1 = Red
	2 = Green
	3 = Blue
	4 = Cyan
	5 = Yellow
	6 = Magenta
	7 and higher = White

2. DR-Graph colours
------------------
  DR Graph uses GSX function 14 to map the colours as follows:

	0 = Black
	1 = White
	2 = Red
	3 = Green
	4 = Blue
	5 = Cyan
	6 = Yellow
	7 = Magenta
	8 and higher = White

  This test screen attempts to do the same.

  Depending on the driver, this should either reprogram the screen's palette 
(in which case colours already on the screen will change), or just change what 
colours will be used going forward (in which case existing colours will 
remain unchanged).

3. IBM 3270 colours
------------------
  This behaves similarly to DR Graph, except the colours requested, rather 
than being simple RGB, are based on those used by IBM 3270-type terminals. The
intention is to see how the driver handles colours which are not simple RGB 
combinations. It may map them to the nearest equivalent it has, or reprogram
the palette to render them exactly.

4. Palette change while drawing
-------------------------------
  This lists the first 16 colours using the default palette, then changes to
the 3270 palette and draws them again. On a palette-based display, both 
columns will now be displayed in the same colours, using the mapping for the
3270 palette. On a fixed-colour display, the colours in the left column will 
not be affected by the palette change, but the right column should be drawn
using the 3270 colours or the best approximation the driver can manage.

5. All colours / truecolour
---------------------------
  The bottom half of the screen will be filled with as many colours as will 
fit (in strips approximately 2 pixels wide; rounding errors mean there may 
be the occasional gap, depending on your screen).

  On a palette-based display, the top half of the screen should be solid 
green. On a fixed-colour display the top half should display some approximation
to a colour gradient (colour 2 is repeatedly reassigned with different colours
and then a line is drawn in colour 2).

Escape tests
============

  In GSX, escape functions tend to be implemented only on screen devices. On 
a printer or a plotter device, only the first test (get screen size) is 
likely to do anything, and it should return the 'unsupported' value of 
65535 x 65535.

The tests are:

1. Get text screen size
-----------------------
  Should return the size of the text screen, or 65535 x 65535 (ie, -1 x -1) if
there is no text mode for this device.

  Note that a warning [GSX claims 0 values returned] may be displayed; this 
happens if the GSX driver did not correctly set the number of integer values 
returned in INTOUT.

2. Text screen output / cursor control
--------------------------------------
  Should clear the screen to a text pattern, in four quadrants. Clockwise 
from top left, these should be spaces, inverse stars, dashes, inverse hashes.
It will also print a list of keys:

  H/J/K/L to move the cursor
  C to clear to end of screen
  D to clear to end of line
  A to move the cursor to the top left corner of the screen
  G to get the cursor position
  M/ESC to end the test

3. Query mouse
--------------
  Should display 1 if a mouse, tablet or similar pointing device is available,
  0 if not. Again, the warning [GSX claims 0 values returned] will be displayed
  if no answer at all was made -- in which case, it's safest to assume that 
  there is no pointing device present.

4. Hard copy
------------

  Generates a test screen in the usual way, then tries to dump it to the 
printer. If this operation isn't supported nothing will happen.

5. Graphics cursor
------------------

  Generates a test screen, and then superimposes the graphics cursor. Use 
H/J/K/L to move it around the screen, M or ESC to end the test.

Fill tests
==========

  On devices that don't support area fill, this should fall back to drawing
an outline. The tests are:

1. Fill hollow
--------------
  Fill the screen with 64 stars in up to 8 colours. The columns across the 
page will use graphics modes REPLACE, TRANSPARENT, XOR and ERASE in order.
The interiors of the stars will use the hollow pattern (black in REPLACE 
mode, not drawn otherwise). 

2. Fill solid
-------------
  As Fill hollow, but the interiors of the stars will be filled with the 
solid pattern (foreground colour in modes REPLACE, TRANSPARENT, XOR; 
background colour in ERASE). The fill algorithm should fill the tips of the
star but leave the centre untouched.

3. Fill pattern
---------------
  As Fill hollow, but the interiors of the stars will be filled with one
of the greyscale patterns.

4. Fill hatch
-------------
  As Fill hollow, but the interiors of the stars will be filled with one
of the hatch patterns.

5. Fill all patterns
--------------------
  Fills the screen from the bottom up with octagons, containing all fill
patterns and hatches supported by this driver. 

General Drawing Primitive tests
===============================

  General Drawing Primitives are optional parts of GEM, so it's quite possible
that some or all of these functions will not have any effect. For example, the
Epson printer drivers DDFXHR8 / DDFXLR8 only implement the bar primitive, so
will only produce meaningful output on the first three tests.

1. Bar mode/colour
------------------
  Fill the screen with rectangles in up to 8 colours. The columns across the 
page will use graphics modes REPLACE, TRANSPARENT, XOR and ERASE in order.
The interiors of the rectangles will use a 50% grey pattern.

2. Bar all patterns
-------------------
  Fills the screen from the bottom up with rectangles, containing all fill 
patterns and hatches supported by this driver. 

3. Bar all colours
------------------
  Fills the screen from the bottom up with solid rectangles, using all colours
supported by this driver.

4. Arc mode/colour
------------------
  Draws 64 arcs each of just under a quadrant, in up to 8 colours and four
writing modes. 
 
5. Arc mode/pattern
-------------------
  Draws 64 arcs each of just under a quadrant, using up to 8 line patterns and 
four writing modes.

6. Arc mode/width
-----------------
  Draws an arc of just under a quadrant, using up to 8 line patterns and 
line widths (if the driver supports wide lines).

7. Pie slice mode/colour
------------------------
  Draws 64 pie slices (again, of just under a quadrant) using up to 8 colours
and four writing modes.

8. Pie slice mode/pattern
-------------------------
  Draws 64 pie slices as above, using up to 8 fill patterns and four writing
modes.

9. Circle mode/colour
---------------------
  Draws 64 circles using up to 8 colours and four writing modes.

A. Circle mode/pattern 
---------------------
  Draws 64 circles using up to 8 fill patterns and four writing modes.

Input tests
===========
  GSX workstations may have no input support at all, or they may support
multiple devices in up to four classes. 

  By default, all the tests will use input device number 1. Press D to cycle
through values 1-9. In practice locators may use device numbers 1 or 2, and
other device classes will probably stick to number 1.

  Input devices can be operated in request mode (in which the call does not
return until input is available) or sample mode (when the call returns 
immediately).

1. Locator (request)
--------------------
  The screen will display a test pattern and a mouse pointer, which it should
be possible to position using the cursor keys. When the mouse is clicked or 
a key is pressed, the screen will display the results: the coordinates of 
the mouse pointer, and the code of the key / mouse button pressed.

2. Locator (sample)
-------------------
  This reads the pointer position continuously (no cursor displayed) and 
shows the results of the last read. Press ESCAPE to finish (you may need 
to press it a few times).

3. Valuator (request) / 4. Valuator (sample) / 
5. Choice (request) / 6. Choice (sample)
----------------------------------------------
  These work like the locator, except that there's no test pattern or mouse
pointer. In request mode they wait until input, then display the result. In
sample mode they continually poll the input and display the result until the
Escape key is pressed.

  Valuator and choice support is largely theoretical as I haven't found an
original GSX-80 driver that implements it.

7. String (request) / 8. String (sample)
----------------------------------------
  Again, this is largely untested. In request mode the you should key a 
string (which should be echoed to the screen). When you press RETURN, that
string should be returned to GSXTEST and another copy of it printed. In 
sample mode, any characters you type should be echoed until Escape is pressed.

Line tests
==========
  The line is one of the most fundamental aspects of drawing with GSX, so 
the tests here are probably the ones most likely to work -- or the ones you
should be concentrating on first, if you're writing a driver.

1. Polyline mode/colour 1
-------------------------

  Draws groups of eight diagonal lines in up to eight colours and using 
four writing modes. This is intended to exercise the 'dy >= dx' and 'dy < dx' 
code paths often found in line-drawing algorithms.

2. Polyline mode/colour 2
-------------------------
  Draws five-pointed stars in up to eight colours and using four writing 
modes. This is intended to exercise any special case for horizontal lines.

3. Polyline mode/style 1; 4. Polyline mode/style 2.
---------------------------------------------------
  Tests 3 and 4 display the same patterns as tests 1 and 2, but in the 
various line styles supported by GSX (dashed, dotted, dash dot, etc.)

5. Polyline mode/width 1; 6. Polyline mode/width 2.
---------------------------------------------------
  Tests 5 and 6 display the same patterns as tests 1 and 2, but in a
variety of line widths. If the driver doesn't support multiple line
widths, they should all display using the usual 1-pixel-wide lines.

Polymarker tests
================

  The polymarker tests print a dummy caption at the top of the screen. This
is to work around a bug in the Digital Research Epson FX printer drivers, 
which don't draw markers until an instruction to draw text has been processed.

1. Polymarker mode/style
------------------------
  Draws 64 groups of four polymarkers, in up to 8 supported styles and 4
writing modes.

2. Polymarker mode/colour
-------------------------
  Draws 64 groups of four polymarkers, in up to 8 colours and 4 writing modes.

3. Polymarker mode/height
-------------------------
  Draws 64 groups of four polymarkers, in up to 8 sizes (if the driver 
supports multiple polymarker sizes) and 4 writing modes.

3. Polymarker style/height
-------------------------
  Draws 64 groups of four polymarkers, in up to 8 sizes (if the driver 
supports multiple polymarker sizes) and up to 8 styles.

Text tests
==========

1. Text info
------------
  Requests the character and cell size for text at different sizes 
(0%, 100%, 150% and 200% of the minimum size supported by the driver).

2. Text mode/colour
-------------------
  Draws text in the default size, in up to 8 colours and 4 writing modes.

3. Text mode/size
-----------------
  Draws text in as many sizes as will fit on screen, in 4 writing modes. 
Each piece of text is of the form "rrr->aaa" where r is the size requested
and a is the actual size in use.

4. Text mode/fonts
------------------
  Draws text in the default size, in up to 8 fonts and 4 writing modes.

5. Text rotation
----------------
  Draws a circle of text at the default size. If the driver supports text 
rotation, each piece of text will be angled by the amount shown (eg '400' 
for 40.0 degrees).

6. Text alignment
----------------
  Attempts to draw text in four modes, aligned at every possible pixel offset.
This is to try and exercise code paths which optimise output of text when it
doesn't have to be shifted / rotated to match screen bytes.

Workstation info
================
Displays the information that the driver supplies about itself when opened.

The bottom line of hex words is the PTSOUT array, giving:
* Unused, minimum character height
* Unused, maximum character height
* Minimum line width, unused
* Maximum line width, unused
* Unused, minimum marker height
* Unused, maximum marker height


