=========================================
    HIRES.KCL
=========================================
   HiResColour + TEXT WINDOWS
   LIBRARY FOR KAMASOFT C'
=========================================

The library is loaded in the compilation
phase (ExT, G) to the upper part of
memory. Declare it once with extern
"hires.kcl"; then call its functions
directly, like ordinary functions. No per-
function extern is used.

HIRES drives the ZX HiResColour (HRC)
screen: 512x192 pixels with one attribute
per 8x4-pixel cell (64x48 cells, classic
ZX attribute byte).

HRC in the KAMASOFT C' Compiler is drawn
in the second, shadow videoram, page-7
buffer: pixels C000h-EFFFh, attributes
F000h-FBFFh.

HRC works also on bare machines with 48KB
(without paging) if the hardware addon can
provide the zx128 shadow videoram
register.

HRCON pins page 7 to 49152, clears the
whole screen to 0, and initialises all of
the library's own state, which lives at
fixed addresses right after the screen
(from FC00h). HRCON also sets up the text
windows: window 0 becomes the full screen
and windows 1-7 are cleared. HRCON must be
called first.

Colour is the library's own, independent
of BASIC. Set it with HINK and HPAPER.
HPRINT colours the two attribute cells of
every character it prints; HPLOT colours
the cell it plots.

HPRINT uses the font pointer set by HFONT;
HRCON starts it on the ROM font. A
character's glyph is read from font +
code*8. HPRINT and HINPUT each carry their
own glyph-printing routine (HPRINT tuned
for speed, HINPUT for size); nothing is
shared and HRCON installs nothing.

=========================================
  TEXT WINDOWS
=========================================

The library keeps 8 text windows, numbered
0-7. Window 0 is the whole screen and
cannot be redefined. Windows 1-7 start
empty and are set up with HDEFWIN. One
window is active at a time (HWINDOW
selects it); HAT, HPRINT and HINPUT all
work inside the active window.

A window is a rectangle on the 8x4 text
grid: first/last row 0-47 and first/last
column 0-63 (the same grid HAT uses).
Text positions given to HAT are RELATIVE
to the window's top-left corner, and
printing wraps on the window's own edges:
past the last column it returns to the
first column and steps down one text line
(+2 rows); past the last row it wraps back
to the first row (no scroll).

Each window has its own stored cursor and
colour (a full ZX attribute byte). Colour is
kept current by HINK/HPAPER, which write the
active window's record directly. The cursor
follows printing and is saved into the window
when you leave it with HWINDOW, so each window
remembers its last print position. HWINDOW
loads a window's stored cursor and colour
into the live state when it becomes active.
HAT only sets the live cursor temporarily.

All window state lives in page-7 RAM just
above the screen: a small active-window
cache at FCB9h-FCBDh and an 8x7-byte table
at FCC0h-FCF7h. HRCON zeroes the table
(windows 1-7) and fills in window 0. See
SYSTEM VARIABLES below.

=========================================
 COORDINATE SYSTEM
=========================================

Graphics and text use separate grids, but
both count from ZERO. Graphics put the
origin at the BOTTOM-LEFT corner; text
keeps its origin at the top-left.

Graphics (HPLOT, HDRAW, HDRAWTO, HDRAWC,
HDRAWTOC, HCIRCLE, HCIRCLEC):

  (0,0) is the bottom-left pixel.
  X runs 0..511, left to right.
  Y runs 0..191, bottom to top.

  So Y grows UPWARD, exactly like ZX BASIC
  PLOT. The library still draws into a
  top-left framebuffer, so each graphics
  call inverts Y once on entry (memory row
  = 191 - Y) and the pixel address is then
  C000h + (191-Y)*64 + X/8. HDRAWTO takes
  an absolute (X,Y); HDRAW takes a relative
  offset whose dy is also measured upward.

Text (HAT, HPRINT, HINPUT):

  Text uses the 8x4 attribute grid, so the
  row counts in 4-pixel steps: 0..47 (the
  same 64x48 grid as HRC attributes), and
  column 0..63 (8-pixel steps). Row 0 is the
  TOP row, column 0 the left column; rows
  count downward, like BASIC PRINT AT.

  A character is still drawn full 8x8. Its
  top sits on the chosen 4-pixel row, so you
  can place text every 4 pixels. To keep
  lines from overlapping, a line wrap (and
  the move to the next line) advances the row
  by 2 - a full character height - and wraps
  at 48. HAT takes (row, column) in that
  order; the HRC screen is 64 columns wide,
  not 32.

Everything is zero-based: the lowest valid
value on every axis is 0; there is no
1-based counting anywhere in HIRES.

WINDOWS AND COORDINATES: the graphics
calls (HPLOT, HDRAW, ...) are NOT affected
by windows - they always address the whole
512x192 screen. Only the text calls
(HAT, HPRINT, HINPUT) and HCLS are
window-aware. HAT(row,column) is
measured from the active window's top-left
corner.

=========================================
  FUNCTION LIST
=========================================

name     bytes  input  output
-------  -----  -----  ------
HAT      44      2       0
HBORDER    25      1       0
HBOX      235      4       0
HBOXC     385      4       0
HCIRCLE   526      3       0
HCIRCLEC  566      3       0
HCLS      236      1       0
HDEFWIN   110      5       0
HDRAW     326      2       0
HDRAWC    398      2       0
HDRAWTO   319      2       0
HDRAWTOC  391      2       0
HFADEOUT  216      1       0
HFILL     724      3       0
HFONT       4      1       0
HINK       23      1       0
HINPUT    311      2       1
HPAPER     26      1       0
HPLOT      90      2       0
HPRINT    338     1+       0
HRCOFF     34      0       0
HRCON     135      0       0
HWINDOW    89      1       0

Note: HPRINT takes a variable input (a
format plus 0 to N values). HCLS, HAT,
HPRINT and HINPUT act on the active window;
HDEFWIN and HWINDOW manage windows.

=========================================
  PARAMETER PASSING
=========================================

- the last (or only) argument is in
  register HL
- all arguments are also in the parameter
  block pointed to by the system variable
  5CB0h. Each argument takes 2 bytes:
     arg1 = ((5CB0))+0 and +1
     arg2 = ((5CB0))+2 and +3   etc.
- the return value (for functions that
  return one) is in register HL (H is 0
  for a byte result)

=========================================
  HAT - set the print position
=========================================

INPUT : 2 - arg1 row, arg2 column
            (relative to the active window)
OUTPUT: 0

Sets the text cursor used by the next
HPRINT or HINPUT. The row and column are
measured from the active window's top-left
corner, on the 8x4 grid (a character can
start every 4 pixels), and are clamped to
the window. HAT(0,0) is always the
window's own corner. This is a temporary
live setting - it is not written to the
window record. The window's remembered
position follows printing and is saved when
you leave the window with HWINDOW.

USAGE:
  extern "hires.kcl";
  { hat(2,4); hprint("HELLO"); }


=========================================
 HBORDER - set the border colour
=========================================

INPUT : 1 - arg1 colour 0-7, 8 =
            paper, 9 = ink
OUTPUT: 0

Sets the ZX border directly through the
I/O port (it uses nothing from the ROM).
0-7 set that colour. 8 follows the
current library PAPER, 9 follows the
current INK (set by HINK/HPAPER). KCC
does not tell a function how many
arguments it got, so a true no-argument
form is not possible; 8 and 9 play that
role.

USAGE:
  extern "hires.kcl";
  {
  hink(7); hpaper(1);
  hborder(8);   /* border = paper */
  hborder(9);   /* border = ink   */
  }


=========================================
 HBOX - draw a rectangle (pixels only)
=========================================

INPUT : 4 - arg1 X1 (0-511), arg2 Y1
            (0-191), arg3 X2 (0-511),
            arg4 Y2 (0-191)
OUTPUT: 0

Draws the outline of the rectangle whose
opposite corners are (X1,Y1) and (X2,Y2),
as pixels only; the colour stays whatever
the crossed cells already hold, exactly
like HDRAW and HCIRCLE. The corners may be
given in any order (they are sorted). A
zero width or height draws a single line
or dot.

It walks the four sides in one pass and
carries the pixel address and bit mask
incrementally, like HDRAW, so there is no
per-side address setup. It changes no
cursor and no attribute; for a coloured
frame set the cells first or use HBOXC.
Uses AF,BC,DE,HL; keeps IX,IY.

USAGE:
  extern "hires.kcl";
  {
  hrcon();
  hbox(64,32,447,159);
  }


=========================================
 HBOXC - draw a rectangle, coloured
=========================================

INPUT : 4 - arg1 X1 (0-511), arg2 Y1
            (0-191), arg3 X2 (0-511),
            arg4 Y2 (0-191)
OUTPUT: 0

Exactly like HBOX (same outline, same
pixels), but each 8x4 cell the outline
crosses is also set to the current library
colour (HINK/HPAPER), like HPLOT and
HCIRCLEC. Use it for a frame in its own
colour without colouring the cells first.

The four sides snap to whole cells, so the
coloured frame is one cell (8x4 pixels)
thick and the four corner cells are shared.
Both the pixels and the cells are laid down
by walking the perimeter once, so for a
rectangle it colours the same cells as a
per-pixel method would, but faster. Uses
AF,BC,DE,HL; keeps IX,IY.

USAGE:
  extern "hires.kcl";
  {
  hrcon();
  hink(5); hboxc(64,32,447,159);
  }


=========================================
 HCIRCLE - round circle (pixels only)
=========================================

INPUT : 3 - arg1 X (0-511), arg2 Y
            (0-191), arg3 R (radius)
OUTPUT: 0

Draws a round circle with centre (X,Y)
and radius R on the HRC screen, like
CIRCLE in zxgfx.kcl. It is a midpoint
ellipse (a signed integer decision
variable) plotting four symmetric points
per step.

The HRC screen is 512 pixels wide on the
same physical width as the 256 mode, so
one X pixel is only half as wide as a Y
pixel is tall. To make the circle look
truly round (as it would at 256x192),
every horizontal offset is doubled and
the vertical one is left alone. So R is
the vertical radius and the horizontal
radius is 2*R: the circle and its
bounding box span 2:1 in pixels but come
out round on the glass.

It draws pixels only and keeps whatever
colour the cells already hold, like
HDRAW. For a circle in its own colour
use HCIRCLEC.

R=0 draws nothing. The circle must fit on
screen: X-2*R..X+2*R within 0-511 and
Y-R..Y+R within 0-191.

USAGE:
  extern "hires.kcl";
  {
  hrcon();
  hcircle(256,96,40);
  }


=========================================
 HCIRCLEC - round circle, coloured
=========================================

INPUT : 3 - arg1 X (0-511), arg2 Y
            (0-191), arg3 R (radius)
OUTPUT: 0

Exactly like HCIRCLE (same round circle,
same pixels), but each 8x4 cell a point
falls in is also set to the current
library colour (HINK/HPAPER), like HPLOT.
Use it for a circle in its own colour
without filling the cells first.

It colours per point (it works out the
cell for each of the four symmetric
points), so it is somewhat slower than
HCIRCLE. If you do not need the colour,
use HCIRCLE.

Same fit rule and R=0 behaviour as
HCIRCLE, and it keeps IX/IY.

USAGE:
  extern "hires.kcl";
  {
  hrcon();
  hink(2); hcirclec(256,96,40);
  }


=========================================
  HCLS - clear a window
=========================================

INPUT : 1 - arg1 window number 0-7
OUTPUT: 0

Clears a window. HCLS(0) clears the WHOLE
screen: all pixels to 0 and every
attribute cell to the current colour
(HATTR). HCLS(N) for N=1-7 clears only
that window's rectangle - its pixels to 0
and its attribute cells to the window's
own colour - and homes its cursor to the
top-left corner. If the cleared window is
the active one, the live cursor is homed
too. Set HINK/HPAPER before calling to
choose the colour.

USAGE:
  extern "hires.kcl";
  {
  hrcon(); hink(5); hpaper(0);
  hcls(0);        /* whole screen */
  hdefwin(1,0,9,0,31); hwindow(1);
  hink(7); hpaper(2); hcls(1); /* window 1 */
  }


=========================================
  HDEFWIN - define a window
=========================================

INPUT : 5 - arg1 number 1-7,
            arg2 first row, arg3 last row,
            arg4 first col, arg5 last col
OUTPUT: 0

Defines window N (1-7) as the rectangle
first row..last row (0-47) by first
column..last column (0-63) on the 8x4 text
grid. The window's cursor is homed to its
top-left corner and it takes the current
colour (HINK/HPAPER at the time of the
call). Window 0 is fixed and any attempt to
redefine it is ignored.

Defining a window also makes it the active
one: N's bounds, home cursor and colour
become the live state and N is recorded as
active. It only touches its own window - the
window being left is not saved or changed.
So HPRINT, HCLS and the rest act on the new
window straight away, with no separate
HWINDOW call.

USAGE:
  extern "hires.kcl";
  {
  hink(6); hpaper(1);
  hdefwin(2,20,29,32,63); /* now active */
  hcls(2);
  }


=========================================
 HDRAW - draw a relative line
=========================================

INPUT : 2 - arg1 dX, arg2 dY (signed)
OUTPUT: 0

Draws a line (pixels only) from the
graphics cursor to (gx+dX, gy+dY) and
moves the cursor to that endpoint. The
colour is whatever the crossed cells
already hold.

Speed: the pixel address and bit mask are
carried incrementally and the loop runs a
fixed step count, so it draws exactly the
same pixels as before but several times
faster, with no slow byte-aligned case.

USAGE:
  extern "hires.kcl";
  {
  hplot(0,0); hdraw(100,50);
  }


=========================================
 HDRAWC - relative line, coloured
=========================================

INPUT : 2 - arg1 dX, arg2 dY (signed)
OUTPUT: 0

Like HDRAW, but each 8x4 cell the line
crosses is also set to the current
library colour (HINK/HPAPER), exactly as
HPLOT colours its cell. The pixels drawn
are identical to HDRAW; only the colour
is added. Use it for a line in its own
colour without filling the cells first.

It carries the attribute address beside
the pixel address and writes the cell on
every pixel; a new cell row is spotted
from the pixel-address high byte, so no
extra Y counter is needed. Roughly 6 to
15 percent slower than HDRAW (more on
steep lines).

Same cursor behaviour as HDRAW: the
graphics cursor moves to the endpoint.

USAGE:
  extern "hires.kcl";
  {
  hink(2); hplot(0,0); hdrawc(100,50);
  }


=========================================
 HDRAWTO - draw a line to a point
=========================================

INPUT : 2 - arg1 X (0-511), arg2 Y
            (0-191)
OUTPUT: 0

Draws a line (pixels only) from the
graphics cursor to (X,Y) and moves the
cursor to (X,Y). The colour is whatever
the crossed cells already hold.

Speed: the pixel address and bit mask are
carried incrementally and the loop runs a
fixed step count, so it draws exactly the
same pixels as before but several times
faster, with no slow byte-aligned case.

USAGE:
  extern "hires.kcl";
  {
  hplot(0,0); hdrawto(511,191);
  }


=========================================
 HDRAWTOC - line to a point, coloured
=========================================

INPUT : 2 - arg1 X (0-511), arg2 Y
            (0-191)
OUTPUT: 0

Like HDRAWTO, but each 8x4 cell the line
crosses is also set to the current
library colour (HINK/HPAPER), like HPLOT.
The pixels are identical to HDRAWTO; only
the colour is added.

Same incremental colouring as HDRAWC, and
the same cursor behaviour as HDRAWTO: the
graphics cursor moves to (X,Y).

USAGE:
  extern "hires.kcl";
  {
  hink(6); hplot(0,0);
  hdrawtoc(511,191);
  }


=========================================
 HFADEOUT - fade attributes to black
=========================================

INPUT : 1  - arg1 window number 0-7
            (0 = whole screen)
OUTPUT: 0

Fades attributes to black in 8 steps, like
the standard-screen FADEOUT but on the
HiResColour attribute map. Each step lowers
the INK and PAPER code by one and clears
BRIGHT (FLASH stays), with a short frame-
synced pause so the fade is visible.

arg1 selects what fades: 0 is the whole
screen (all cells), 1-7 is that text window
only - its attribute cells are read from the
window table, so it respects the bounds set
by HDEFWIN. Pixels are left untouched; only
attributes change, so text and shapes keep
their form while their colour dims away.

Like FADEOUT, the whole-screen form (arg 0)
also dims the border one shade per step
through BORDCR (5C48h) and OUT 254; a window
leaves the border alone.

The pause uses HALT, so interrupts must be
enabled (the normal state). Uses AF,BC,DE,
HL; keeps IX,IY.

USAGE:
  extern "hires.kcl";
  {
  hrcon();
  /* ... draw something ... */
  hfadeout(0);   /* fade the whole screen */
  }


  HFILL - pattern flood fill
=========================================

INPUT : 3 - arg1 x (0-511), arg2 y (0-191),
            arg3 character code
OUTPUT: 0

Flood-fills the empty (0) area that holds
the point (x,y) with the pattern of a
character - its 8x8 glyph in the current
font (FONTP + code*8, as HPRINT). Pixels
only; colour is left alone. The fill is
4-connected: it spreads left, right, up and
down through empty pixels but not
diagonally, so a one-pixel diagonal gap
stops it. Any set (1) pixel is a wall; if
(x,y) is itself set, nothing happens.

Two passes. Pass 1 fills the region solid
with a scanline flood fill, using a private
seed stack at FD00h-FFFFh (768 bytes), and
records the bounding box. Pass 2 ANDs the
glyph over that box, so the solid fill takes
the character's shape (a 0 bit of the glyph
clears a pixel, a 1 bit keeps it).

The pattern is ANDed over the whole
bounding box, so every set pixel inside
that box - including the parts of the
outline that fall within it - also takes
the pattern, and a 0 bit of the glyph
clears it. A rectangle's outline lies just
outside the box on all four sides and stays
solid, but a curved or sloped outline (a
circle) has much of its boundary inside the
box, so that part is patterned and partly
erased. Re-draw the outline after HFILL for
a clean edge. The seed stack is capped - on
a hugely fragmented region it stops growing
(the fill may be left incomplete) rather
than overrunning memory.

USAGE:
  extern "hires.kcl";
  {
  hbox(20,20,60,50);
  hfill(40,35,46);
  }


=========================================
 HFONT - set the font
=========================================

INPUT : 1 - arg1 font address
OUTPUT: 0

Sets the pointer to the font used by
HPRINT. A character's glyph is read from
font + code*8, so the address you pass
depends on the font layout. For a full
256-character font (glyph for code 0
first) pass the start of the data. For a
ROM-style font that starts at code 32
(like the built-in one) pass start-256,
so code 32 lands on the first glyph. KCC
gives no address to data placed by
inline, so the practical way to supply a
font is a char array (load it, then take
its address with &). HRCON resets the
font to the ROM font, so call HFONT after
HRCON.

USAGE:
  extern "hires.kcl";
  declare char font[768];   /* 96 chars * 8 */
  {
  hrcon();
  /* fill font[] from a file with
     esxdos.kcl, then: */
  hfont(&font[0]-256); /* 32-based */
  hprint("ABC");
  }


=========================================
 HINK - set the ink colour
=========================================

INPUT : 1 - arg1 ink (0-7)
OUTPUT: 0

Sets the ink of the library colour used by
HPRINT, HPLOT and HCLS - the library's own
colour, separate from BASIC. It changes both
the live colour and the active window's own
stored colour, so the ink belongs to that
window and survives a later HWINDOW. Takes
effect on the next thing drawn or cleared.

USAGE:
  extern "hires.kcl";
  {
  hink(6); hpaper(0); hcls();
  }


=========================================
  HINPUT - read a line in the active window
=========================================

INPUT : 2 - arg1 buffer, arg2 size
OUTPUT: 1 - the length in HL

Reads a line from the ROM keyboard,
echoing printable characters, so the echo
is coloured, wraps and steps exactly like
HPRINT inside the active window. ENTER
finishes; DELETE erases the last
character, moving the cursor back within
the window (at the window's left column it
steps up one line to the last column).
Stores up to size-1 characters (max 255),
0-terminates the buffer and returns the
length.

HINPUT is self-contained and tuned for
size: it carries its OWN glyph routine
(compact, looped) reached by one
relocatable CALL whose operand it patches
at entry from its own load address. It is
independent of HRCON and of HPRINT - each
has its own copy of the drawing code.

USAGE:
  extern "hires.kcl";
  declare char name[16];
  { hat(2,0); hinput(name,16); }


=========================================
 HPAPER - set the paper colour
=========================================

INPUT : 1 - arg1 paper (0-7)
OUTPUT: 0

Sets the paper of the library colour used by
HPRINT, HPLOT and HCLS - the library's own
colour, separate from BASIC. It changes both
the live colour and the active window's own
stored colour, so the paper belongs to that
window and survives a later HWINDOW. Takes
effect on the next thing drawn or cleared.

USAGE:
  extern "hires.kcl";
  {
  hink(7); hpaper(1);
  }


=========================================
 HPLOT - plot a pixel
=========================================

INPUT : 2 - arg1 X (0-511), arg2 Y
            (0-191)
OUTPUT: 0

Sets one pixel and colours its 8x4
attribute cell with the current library
colour (HINK/HPAPER). Stores (X,Y) as the
graphics cursor for HDRAW/HDRAWTO.

Speed: the byte column X>>3 is computed
once for both the pixel and the cell,
the bit mask is built directly (byte-
aligned X no longer loops) and the cell
row uses (Y and FCh)*16. Same pixel,
cell and cursor as before, about 1.3x
faster, over 10x on byte-aligned X.

USAGE:
  extern "hires.kcl";
  {
  hink(2); hplot(256,96);
  }


=========================================
  HPRINT - print text in the active window
=========================================

INPUT : 1+ - arg1 string, plus one
             value per %N
OUTPUT: 0

Prints text at the text cursor using the
library font, in the active window's
colour, drawing the glyph pixels AND
colouring the two 8x4 attribute cells of
each character. Controls: \N newline, \T
tab to the next 8-column stop, %N prints
the next value as unsigned decimal
(0-65535), %% prints a literal %.

All wrapping happens on the ACTIVE
WINDOW's edges (no scroll): at the last
column the cursor returns to the window's
first column and steps down one text line;
at the last row it wraps back to the
window's first row. \N and \T stay inside
the window too.

HPRINT is self-contained and tuned for
speed: it carries its OWN glyph routine
(straight-line, unrolled) at the end of
its body. As printing a character is
reached from several places inside HPRINT,
that routine is a subroutine; at entry
HPRINT reads its own load address and
patches the operand of the single CALL
that reaches it, so it stays correct after
the compiler relocates the body. It uses
no shared code and does not depend on
HRCON.

USAGE:
  extern "hires.kcl";
  {
  hat(0,0);
  hprint("SCORE: %N\NLIVES: %N",10,3);
  }


=========================================
 HRCOFF - turn HiResColour off
=========================================

INPUT : 0
OUTPUT: 0

Disables HRC and restores the ordinary ZX
display (page 5, ZX48 ROM) with one hard-
coded OUT to 7FFDh. It also restores the MB03
video timing saved by HRCON (read from FC1Bh,
written back to m_zxi_009).

USAGE:
  extern "hires.kcl";
  {
  hrcoff();
  }


=========================================
  HRCON - turn HiResColour on
=========================================

INPUT : 0
OUTPUT: 0

Enables HRC, pins page 7 as the displayed
video RAM, saves and sets the MB03 video
timing, clears the whole screen to black
and initialises all library state at
FC00h: cursors 0, colour INK 7 PAPER 0,
font = ROM font (3C00h).

It also sets up the text windows: window 0
is made the full screen (rows 0-47,
columns 0-63, INK 7 PAPER 0) and becomes
active; windows 1-7 are zeroed. Call HRCON
before any other HIRES function.

HRCON no longer installs any print
routine: HPRINT and HINPUT each carry
their own (see STANDALONE PRINT ROUTINES),
so there is nothing shared to set up.

USAGE:
  extern "hires.kcl";
  { hrcon(); }


=========================================
  HWINDOW - select the active window
=========================================

INPUT : 1 - arg1 window number 0-7
OUTPUT: 0

Makes window N the active one. On the way
out it saves the live cursor into the window
being left, so each window remembers its
last print position; then it loads N's
bounds, cursor and colour into the live
state and records N as active. The colour is
not saved on leaving - HINK/HPAPER keep each
window's colour current directly. Window 0
is always the whole screen.

USAGE:
  extern "hires.kcl";
  {
  hdefwin(1,0,9,0,31);
  hwindow(1); hprint("in window 1");
  hwindow(0); hprint("full screen");
  }


=========================================
  STANDALONE PRINT ROUTINES
=========================================

There is no shared print routine. HPRINT
and HINPUT each carry their OWN glyph
routine in their own body; HRCON installs
nothing. All volatile scratch lives in one
shared pool at FC90h-FCB7h (see SYSTEM
VARIABLES).

Both routines do the same work - ENTRY A =
character code: draw the glyph from font
ptr (FC19h) + code*8, 8 rows at 64-byte
pitch, colour both 8x4 attribute cells
with HATTR (FC18h), and advance the text
cursor INSIDE THE ACTIVE WINDOW, wrapping
on the column bound (FCBDh) and row bound
(FCBBh) and resetting to the window first
column/row (FCBCh/FCBAh). They USE
AF,BC,DE,HL; keep IX,IY.

HPRINT tunes this for speed (straight-
line, unrolled blit); HINPUT tunes it for
size (a looped blit). Because a KCL body
is relocated by the compiler, neither can
CALL a fixed or internal address directly:
at entry each reads its own load address
(from the CALL that invoked it) and
patches the operand of the single CALL
that reaches its routine, so the CALL is
correct wherever the body lands.

=========================================
  SYSTEM VARIABLES (shared library state)
=========================================

HRCON builds all state in the free page-7
RAM just after the HRC screen, from FC00h.
Addresses are in page 7 (reachable at
C000h-FFFFh only while HRC is on). A word
is stored low byte first.

Persistent state (kept until changed):

addr   size  meaning
-----  ----  --------------------------------
FC00h  word  graphics cursor X (0-511)
FC02h  byte  graphics cursor Y (0-191)
FC03h  byte  text cursor row 0-47 (absolute)
FC04h  byte  text cursor column 0-63 (absol.)
FC18h  byte  current colour - hattr (a ZX
             attribute byte)
FC19h  word  font pointer (glyph = font+code*8)
FC1Bh  byte  saved MB03 video timing

Window active-cache (loaded by HWINDOW,
read by the print routine):

FCB9h  byte  ACTWIN - active window number 0-7
FCBAh  byte  WFR - active first row
FCBBh  byte  WRB - active row wrap bound
             (= last row)
FCBCh  byte  WFC - active first column
FCBDh  byte  WCB - active col wrap bound
             (= last column + 1)

Window table (8 windows x 7 bytes) at FCC0h.
Entry N is at FCC0h + N*7:

off  meaning
---  ------------------------------------
 +0  first row 0-47
 +1  last row  0-47
 +2  first column 0-63
 +3  last column 0-63
 +4  cursor row (absolute)
 +5  cursor column (absolute)
 +6  colour attribute byte

HRCON zeroes windows 1-7 and fills window 0
with the full-screen bounds. HDEFWIN writes an
entry AND makes that window active. HWINDOW
loads a window's entry into the live state
and, on leaving, saves the live cursor into
the old window. HINK and HPAPER write the
colour into the active window's entry.

=========================================
  Internal scratch (volatile)
=========================================

Working areas, reused within a single call
and carrying nothing between calls. They all
share ONE pool at FC90h-FCB7h (40 bytes),
sized to the biggest user (the circle); as no
two ever run nested they safely overlay the
same bytes:

addr           used by      purpose
-------------  -----------  -----------------
FC05h-FC07h    HPRINT       format parser +
                            format pointer
                            (kept between
                            calls)
FC90h-FCB7h    HCIRCLE,     one shared temp
               HCIRCLEC,    pool (volatile):
               HDRAW/C,     circle worker;
               HDRAWTO/C,   Bresenham line;
               HINPUT,      input ptr/count;
               HPRINT,      digit buffer;
               HCLS,        clear rectangle;
               HBOX/HBOXC,  rectangle bounds;
               HFADEOUT,    fade bounds;
               HFILL        fill bbox + glyph

HFILL also uses FD00h-FFFFh as a 768-byte
flood-fill seed stack during a call.

Each of HPRINT and HINPUT holds its own glyph
routine at the end of its own body (no shared
code).

=========================================
  Layout summary
=========================================

C000h-EFFFh  HRC pixels
F000h-FBFFh  HRC attributes
FC00h-FC04h  graphics + text cursor
FC05h-FC07h  HPRINT format state
FC08h-FC17h  free
FC18h-FC1Bh  HATTR, FONTP, TIMSAV
FC1Ch-FC8Fh  free
FC90h-FCB7h  shared temp pool (volatile)
FCB8h        free
FCB9h-FCBDh  window active-cache
FCBEh-FCBFh  ACTPTR (active window record ptr)
FCC0h-FCF7h  window table (8 x 7 bytes)
FCF8h-FCFFh  free
FD00h-FFFFh  HFILL flood-fill seed stack

=========================================
 End

