Vga Face

The colour face

A package on this machine is drawn for the 1bpp adapters first - black ink, white paper - and on a VGA it looks the same. This skill gives one a second face for a 4bpp display without touching the first: colour where colour carries meaning, a layout cut on the card's own grid, and buttons whose captions sit inside them. And it starts with the redraws, not the paint: a face that is twice as pretty and repaints twice as much is a regression on the machine this OS is for (CLAUDE.md, Performance).

The worked example is MIDIRack: SPEC.md §105.9.4 (the caches), §105.9.5 (the colour face), §13.8.10 (the library hook it needed), apps/midirack/mrui.inc (all of it), tests/mrdraw.py (the instrument) and tools/os88midart.py (the button pictures). Read those before writing a line - this skill is the order they were done in and why, and the code is the reference.

Read LESSONS.md first. Every entry cost a rebuild or a wrong picture during the MIDIRack work, and most of them look like a bug in the package when they are a bug in the method.

Step 0 - scope, and the pictures to keep

• $ARGUMENTS names the package. Read its SPEC.md section and the window code end to end - layout, painter, every caller of a repaint. Check docs/INDEX.md for what the library already gives (os88ui.inc's buttons, check boxes, radio groups, group boxes, scroll bar, About card).
• Take the baseline on all three adapters before changing anything: VGA (os8088_xt_vga), Hercules (os8088_5150_herc_*), CGA (os8088_5150_cga_gla), through MartyPC's fbuf (see Step 6's script shape). The mono pictures are the contract: at the end they must be identical except where you meant them not to be, and you will need the "before" to prove it.
• Work in a worktree of your own (git worktree add), never the main checkout - several sessions write there (docs/UPSTREAM.md, the memory).

Step 1 - measure the redraws (before touching the paint)

PERFORMANCE.md's first sentence: a redraw is priced by the PRIMITIVE CALLS it makes. So count them, per gesture:

• Copy tests/mrdraw.py to tests/<pkg>draw.py. It arms os88marty.bp_trace on the API table's DRAWING CELLS themselves (KERNEL_SEG:0x38 fill, 0x40 frame, 0x1E5 font_run, 0x39D icon, 0x3A4 BLITP, ...) - so the kernel's own painting (menus, the title bar) is never counted - and for each hit reads SS:SP and the far return address: which task made the call (a worker's stack is not the UI task's) and which package routine (the nearest symbol below the return IP, from tests/mrprobe.py-style re-assembly).
• Drive the gestures a user makes: play, pause, a selection move, a skip, a toggle, a card up and down - by KEY where the package has keys, so the menu's own painting stays out of the count.
• Write the numbers down. MIDIRack's first table read Pause 197 calls, of which 152 were the button group drawn twice; Next 229; Stop-when-stopped
  178. The routine names point straight at the waste.

Step 2 - draw what changed (the caches)

The pattern (§105.9.4), one cache per kind of thing on the glass:

• One routine, <pkg>_update, walks the whole window through the caches. Every command calls it instead of a repaint. W_PAINT owes every cache and is otherwise unchanged.
• A card going UP draws the card alone; going DOWN is the one command that repaints - and so is a card replacing another (LESSONS.md).
• THE IDENTITY ASSERTION is what makes the caches trustworthy: after a run of gestures, capture the content, force a full repaint (a card up and down), capture again - identical to the pixel. Put it in the draw test with per-gesture CEILINGS a repaint would blow through, register it as a soak row, and run it on Hercules AND VGA.
• Then re-measure. MIDIRack: 1,177 calls across the gestures became 86.

Step 3 - when to draw the colour face

• Ask the DISPLAY the window is on, at each full paint: OSAPI_WM_DISPLAY (BX = the window) answers DH = bits per pixel; > 1 is colour (§39.16.4; it answers the more restrictive display for a straddle). Not OSAPI_VIDEO - that is the primary's. Bank the answer in a byte the paint sets and every later draw reads (mru_col), so a worker draw and a W_PAINT never disagree mid-flight.
• Gate it on the content box too, and compute the gate from the narrowest real case. MIDIRack's needs 600 x 270: a VGA's window is 624 x 311, an EGA's ~624 x 279 (350 lines less the 20-line menu bar, the dock and the title). Below the gate, a colour display gets the mono face - which is a complete face.
• The compact (CGA) layout is never the colour face.

Step 4 - the layout

• Fixed columns where the mono face uses shares, sized from what must be WHOLE: an 8.3 name (12 cells + mark + scroll bar), the longest label, the longest value. MIDIRack: playlist 140, Now Playing 248, the rack the rest.
• Put anything you will BLITP on the 8-pixel grid. OSAPI_GFX_BLITP takes x on a multiple of 8, and a window's content origin already is one (§11.94) - so it is your own inset that has to be. MIDIRack's transport starts at 152 and steps 48.
• Anchor rows bottom-up so the panes' last rows line up across the window (Load Directory with Eject/Loop, Add/Remove with the transport's bottom edge), and let the tallest flexible element (the display, the list) take what is left.
• Derive pitches (line spacing) from the space left, clamped (10..14), and centre what remains - then check the arithmetic at the EGA height.