vt1200/xie/XIE_COMPRESSION_SCHEMES.md

# Compression schemes in the XIE headers

Two different XIE lineages are vendored here, and they do **not** define the same
set. The terminal speaks the first one.

## DEC XIE 2.3 — what the VT1200's server implements

`docs/dec/xie23/include/dec/extensions/XieAppl.h:151-157` — the complete set,
five values, nothing else:

```c
    /*
    **	Compression Schemes
    */
#define XieK_PCM                0     /* uncompressed                        */
#define XieK_G31D               1     /* CCITT Group 3, one-dimensional      */
#define XieK_G32D               2     /* CCITT Group 3, two-dimensional      */
#define XieK_G42D               3     /* CCITT Group 4                       */
#define XieK_DCT                4     /* JPEG - 2D discrete cosine transform */
```

`XieK_DCT` is the JPEG scheme: the man page says of the `cmpprm` argument that
it "specifies a parameter required **for the DCT compression scheme**"
(`man/XieGetImage.3X:56`, `man/XieSetStream.3X:68`). There is no `XieK_JPEG`
and no TIFF/RLE/LZW/PackBits constant anywhere in the 2.3 headers.

The scheme travels in the SetTransport request as a byte plus a parameter word
(`XieProto.h:538-548`):

```c
typedef struct {
    ...
    CARD32	    compression_parameter;
    CARD8	    compression_scheme;
    CARD8	    mode;
    ...
```

## What the DEC 2.3 server actually accepts

`server/xie/XieTransport.c`, `ProcSetTransport` (line 616 onward) validates the
scheme per image:

```c
	switch( stuff->compression_scheme )
	    {				    /* verify compression_scheme    */
	case XieK_PCM  : break;
	case XieK_G31D :
	case XieK_G32D :
	case XieK_G42D :
	    MatchOkIf_( IsBitonal_(img) && stuff->mode != XieK_Tile, ...);
	case XieK_DCT  :
	    MatchOkIf_(!IsBitonal_(img) && stuff->mode != XieK_Tile
		       && org != XieK_BitByPlane, ...);
	default: BadValue_(stuff->photo_id);
	    }
```

So, concretely:

* **PCM** — always allowed.
* **G31D / G32D / G42D** — require a **bitonal** image and a mode other than
  `XieK_Tile` (i.e. PutStream/GetStream, not PutTile/Tile).
* **DCT (JPEG)** — requires a **non-bitonal** image, a mode other than
  `XieK_Tile`, and a component organization other than `XieK_BitByPlane`.
* Anything else — `BadValue`.

In the transport *implementation* (`ProcGetStream`, line 275 onward) only three
schemes are real, and two are stubs:

```c
	case XieK_DCT  : ... s = DdxEncodeDct_( &Udp_(img,p), ... );  break;
	case XieK_G42D : ... s = DdxEncodeG4_( Udp_(img,p), ... );    break;
	case XieK_PCM  : ...                                          break;
	case XieK_G31D :			/* not yet supported	    */
	case XieK_G32D :			/* not yet supported	    */
	default        : s = BadValue;
```

Same stub pair in `ProcSetStream` (line 1460). The DCT and G4 work is delegated
to the DDX hooks `DdxEncodeDct_` / `DdxEncodeG4_` — i.e. to the image
accelerator on the board, which is why the firmware's DDX render path reports
`DDX_RENDER: unsupported compression scheme` when it cannot service one.

**This is why our working client must use `XieK_PCM`.** It sends a bitonal
64x64 photomap in `mode = XieK_Tile`, and under the rules above that combination
admits PCM only — G3/G4 are refused for Tile mode, and DCT is refused for a
bitonal image. Requesting anything else returns `BadValue`, which is the
`BadValue (integer parameter out of range)` seen in the early runs; `BadMatch`
has the same origin, since these are `MatchOkIf_` checks.

## X Consortium X11R6.1 — a different, larger list

`xc/include/extensions/XIE.h:175-206` (the `xieperf` lineage, not what the
VT1200 runs) uses DecodeTechnique / EncodeTechnique enums with ten codecs:

| constant | value | meaning |
|---|---|---|
| `xieValDecodeUncompressedSingle` | 2 | bitonal & grayscale |
| `xieValDecodeUncompressedTriple` | 3 | colour |
| `xieValDecodeG31D` | 4 | FAX |
| `xieValDecodeG32D` | 6 | FAX |
| `xieValDecodeG42D` | 8 | FAX |
| `xieValDecodeJPEGBaseline` | 10 | grayscale & colour |
| `xieValDecodeJPEGLossless` | 12 | grayscale & colour |
| `xieValDecodeTIFF2` | 14 | TIFF modified G31D |
| `xieValDecodeTIFFPackBits` | 16 | TIFF Apple format |

So JPEG appears in **both** lineages — as `XieK_DCT` (2.3, one value) and as
JPEG baseline/lossless (X11R6.1, two values) — but the 2.3 protocol that the
terminal speaks has only the single Scheme-4 DCT code, with no baseline/lossless
split and no lossless predictor field in the wire struct.

## What THIS ROM actually does (measured, not inferred)

Two probes were built for this (`xiescheme.c` via libXie, and
`xie_schemes_raw.py` which speaks the wire protocol directly):

### 1. At SetTransport (minor 20), raw request, fresh bitonal photomap each time

```
PCM   SetTransport -> ACCEPTED
G31D  SetTransport -> ACCEPTED
G32D  SetTransport -> ACCEPTED
G42D  SetTransport -> ACCEPTED
DCT   SetTransport -> REFUSED  ERROR code=14 (BadIDChoice) minor_op=20
5     SetTransport -> REFUSED  ERROR code=14 (BadIDChoice) minor_op=20
```

So **DCT is answered exactly like an out-of-range scheme value.** Note this is
also evidence that the ROM does *not* implement the reference server's
`IsBitonal_` rules: G42D is accepted even on a 256-level photomap, where
`XieTransport.c` would answer BadMatch.

### 2. At Export (minor 21), with the photomap's compression byte forced

The client's `XieExport` to a depth-1 pixmap, for each value of the photomap's
`compression_scheme` byte (`harness/mame/xie_fix.lua` pokes it at file
`0x1B256`; the server never initialises it, so it holds the heap fill `0x55`):

```
scheme 0  PCM     export: pixmap 4096/4096   no X error
scheme 1  G31D    export: pixmap 4096/4096   no X error
scheme 2  G32D    export: pixmap 4096/4096   no X error
scheme 3  G42D    export: pixmap 4096/4096   no X error
scheme 4  DCT     export: FAILED             BadValue, minor 21
scheme 5  (bogus) export: FAILED             BadValue, minor 21
```

**DCT and a bogus value are treated identically; 0..3 are accepted.** So in this
ROM the valid set is `0..3` and scheme 4 has no implementation — it is refused,
not silently mis-decoded.

### 3. The ROM has no JPEG machinery

Searched `vt1200_v22.bin` (md5 `b46a3e442ccb86134d2356bd70d22fd2`):

* no `JPEG` / `DCT` string (the only compression-related strings are
  `DDX_RENDER: unsupported compression scheme`, `error initializing scalution`
  and `5 - Scalution Test`);
* the standard JPEG Annex K quantisation table is **absent**, in both the
  zigzag order code stores and the natural row order — and no flat 8x8 table
  either. A DCT codec carries one of these; this ROM carries none.

`DDX_RENDER: unsupported compression scheme` exists but did **not** fire in any
of the runs above (0 occurrences in the MAME debug log for schemes 4 and 5), so
it belongs to a path these probes do not reach — reported as an open detail
rather than claimed as the explanation.

### 4. Cross-check: PCM is the only scheme that helps in practice

The working display path uses `XieK_PCM` throughout, because the transport is
`XieK_Tile` on a bitonal image and, per the reference rules above, that admits
PCM only. On a depth-1 server there is no non-bitonal visual, so `XieK_DCT` is
unreachable by protocol rule as well as unimplemented.

## Cross-reference: the DTJ article

`docs/dec/DTJ-1991-v03-04-bitonal-image-accelerators.pdf` — "Hardware
Accelerators for Bitonal Image Processing" (Payson, Cianciolo, Crouse, Winsor;
DTJ Vol. 3 No. 4, Fall 1991). Reading it against the headers above:

* The accelerator ASIC it describes is **bitonal** and is a CCITT decoder: "The
  decompressor chip acts as a CCITT binary image decoder", converting Huffman
  codes to fixed-length codes, and it covers G3-1D, G3-2D and G4-2D. The chip
  set is decompressor + scaler (M:N, 1..127) + rotator — the
  "scalution" hardware the firmware drives.
* JPEG is discussed in the **continuous-tone** section of the same article, not
  as part of that ASIC: "for gray-scale and color images, the Joint
  Photographic Experts Group (JPEG) standard"; "the JPEG compression method is
  based on the two-dimensional (2D) discrete cosine transform (DCT)". For
  hardware it cites C-Cube's **CL550-10 JPEG Image Compression Processor**, not
  the bitonal chip.
* The DECimage 1200 terminal (the image-capable sibling of this unit) is
  described as using this hardware: "The DECimage 1200 can read, transport,
  decompress, scale, and display an 8.5-by-11-inch bitonal document in 1 to 2
  seconds."

So the article's "image board" is the bitonal G3/G4 decompressor, and JPEG/DCT
is the scheme XIE defines for the continuous-tone data type that the same
protocol carries — the two correspond exactly to `XieK_G42D` and `XieK_DCT`.

This is consistent with the measurement above: the ROM has the G3/G4 half
(`0..3` accepted, scalution test present) and no DCT half (scheme 4 refused,
no JPEG tables). The terminal is depth 1, so the continuous-tone data type the
DCT scheme exists for has no visual to land on.