Skip to content

SOURCE-TREE.md

Latest commit

 

History

History
96 lines (66 loc) · 3.4 KB

SOURCE-TREE.md

File metadata and controls

96 lines (66 loc) · 3.4 KB
Raw

Source tree and reading guide

The source is organised around the program's fixed memory map rather than around modern object boundaries. This is deliberate: Screen Machine stores persistent state in instruction operands, uses jump vectors as public interfaces, and installs printer code into three fixed overlay slots.

Canonical composition

src/core/screenmachine_semantic.asm

This file includes all 21 semantic modules in ascending address order and emits one continuous binary from $7600 through $DAFF.

The independent preservation composition is:

src/core/screenmachine_core.asm

It exists to prove that semantic refactoring has not changed the original byte stream. The build requires both compositions to equal src/binary/core-7600.bin.

Shared contracts

src/include/ contains 19 shared definition files:

  • Spectrum ROM, system-variable and display constants;
  • Screen Machine memory planes and state records;
  • the 22-entry public API;
  • subsystem ABI exports for editors, raster tools, UI and main program;
  • Didaktik/UR4 8255 and Centronics parameter contracts.

Defining modules include their own ABI declarations. A moved exported label therefore produces an assembler conflict instead of silently changing a caller.

Main subsystems

Glyph editors — $7600-$7FFF

The shared editor runtime builds panels, enlarged grids and selection maps. The font editor operates directly on four resident 1,536-byte fonts. The pattern and cursor editor modifies the live 8-byte records used by the screen editor.

Initial data and printer slots — $8000-$ABDF

The initial UNDO plane contains the bundled RS2 screen. The first and second printer slots are installable code ranges. Between them live the palette streams, 208 eight-byte tiles and the OR 1 TO 2 operation. $A800-$AAFF is the semantic selector plane parallel to the Spectrum attribute map.

Public API and cursor/input — $ABE0-$AFFF

Twenty-two three-byte JP vectors expose cursor, text and logical-input services without adding stack frames. The cursor renderer uses a fixed private record stack, 8.8 coordinates and masked 8×8 sprites.

Screen editor — $B000-$CEF8

The raster core provides point, line, spray, flood, connected erase and rectangle operations. Higher layers add the movable palettes, magnifier, drawing tools, pattern and attribute painting, window transforms and modal text composition.

UI and executive — $CEF9-$DAFF

The UI runtime renders panel bytecode into visible attributes and the semantic selector plane. The main program controls the menu, BASIC LOAD/SAVE/CAT bridge, font scope, global controls, printer dispatch and return to BASIC.

Historical overlays

Alternative drivers under src/drivers/ are not linked into the uninstalled base core. The installer places them into these ranges:

slot 1   $9B14-$9C3F   controller/front end
slot 2   $A700-$A7FF   sampling and hardware backend
slot 3   $D897-$D89A   COPY/DCOPY vectors

Short Centronics and RS-232 backends occupy documented subranges of those slots.

Where to begin

For the editor architecture, read:

  1. editor/screen_editor_shell.asm;
  2. editor/magnifier_transaction.asm;
  3. graphics/raster_core.asm;
  4. one tool module such as graphics/drawing_tools.asm;
  5. main/main_program.asm.

For the font and pattern editors, begin with editors/glyph_editor_common.asm, followed by either concrete editor.