A menu panel or camera can move towards an endpoint without a different hand-written position for every frame.
Use it in a project
FRACTION is 0–255, mapping exactly to START and ENDPOINT at its two endpoints. Return START+floor((ENDPOINT−START)×FRACTION/255) when ascending; when descending, subtract floor((START−ENDPOINT)×FRACTION/255). This rounds the travel towards START. All inputs are preserved.
Include component.inc once (MOS callers include the shared 6502 implementation through it). Reserve the public fields in this exact order: VALUE, START, ENDPOINT, FRACTION. They occupy 4 contiguous bytes. Also reserve the private workspace: T0, T1, T2, T4, T5, T6, T7, T8, T9, T10, T11 (11 bytes). Array names in the explanation refer to the numbered consecutive bindings, such as C0, C1 and so on.
Call byte_interpolation_init once at the intended reset boundary. It clears inputs as well as outputs and workspace. Set your starting state and configuration afterwards, then call byte_interpolation_step whenever the described event occurs. The helper reads no device, waits for no frame and installs no interrupt handler.
| Ownership | Fields |
|---|---|
| Retain between calls | none |
| Supply before service | START, ENDPOINT and FRACTION |
| Read after service | VALUE |
First measure unsigned travel, scale it by the fraction, then apply that travel in the chosen direction. Dividing by 255 rather than 256 makes both endpoint values exact.
Reusable initialisation and service
; SPDX-License-Identifier: MIT
; Interpolate Between Byte Endpoints. See README.md for the byte interface and ownership.
; init clears the public fields and private workspace; set inputs afterwards.
byte_interpolation_init:
ld a,0
ld (VALUE),a
ld (START),a
ld (ENDPOINT),a
ld (FRACTION),a
ld (T0),a
ld (T1),a
ld (T2),a
ld (T4),a
ld (T5),a
ld (T6),a
ld (T7),a
ld (T8),a
ld (T9),a
ld (T10),a
ld (T11),a
ret
byte_interpolation_step:
; T10 = 0
ld a,0
ld (T10),a
; if ENDPOINT >= START:
ld a,(ENDPOINT)
ld b,a
ld a,(START)
ld c,a
ld a,b
cp c
jp nc,byte_interpolation_L1
jp byte_interpolation_L2
byte_interpolation_L1:
; T11 = ENDPOINT - START
ld a,(ENDPOINT)
ld b,a
ld a,(START)
ld c,a
ld a,b
sub c
ld (T11),a
jp byte_interpolation_L3
byte_interpolation_L2:
; T11 = START - ENDPOINT
ld a,(START)
ld b,a
ld a,(ENDPOINT)
ld c,a
ld a,b
sub c
ld (T11),a
; T10 = 1
ld a,1
ld (T10),a
byte_interpolation_L3:
; T4 = T11
ld a,(T11)
ld (T4),a
; T5 = 0
ld a,0
ld (T5),a
; T1 = FRACTION
ld a,(FRACTION)
ld (T1),a
; T6 = 0
ld a,0
ld (T6),a
; T7 = 0
ld a,0
ld (T7),a
; T0 = 8
ld a,8
ld (T0),a
; while T0 != 0:
byte_interpolation_L4:
ld a,(T0)
cp 0
jp nz,byte_interpolation_L5
jp byte_interpolation_L6
byte_interpolation_L5:
; T9 = T1 & 1
ld a,(T1)
and 1
ld (T9),a
; if T9 != 0:
ld a,(T9)
cp 0
jp nz,byte_interpolation_L7
jp byte_interpolation_L8
byte_interpolation_L7:
; T8 = T6
ld a,(T6)
ld (T8),a
; T6 = T6 + T4
ld a,(T6)
ld b,a
ld a,(T4)
ld c,a
ld a,b
add a,c
ld (T6),a
; T9 = 0
ld a,0
ld (T9),a
; if T6 < T8:
ld a,(T6)
ld b,a
ld a,(T8)
ld c,a
ld a,b
cp c
jp c,byte_interpolation_L10
jp byte_interpolation_L11
byte_interpolation_L10:
; T9 = 1
ld a,1
ld (T9),a
jp byte_interpolation_L12
byte_interpolation_L11:
byte_interpolation_L12:
; T7 = T7 + T5
ld a,(T7)
ld b,a
ld a,(T5)
ld c,a
ld a,b
add a,c
ld (T7),a
; T7 = T7 + T9
ld a,(T7)
ld b,a
ld a,(T9)
ld c,a
ld a,b
add a,c
ld (T7),a
jp byte_interpolation_L9
byte_interpolation_L8:
byte_interpolation_L9:
; T9 = T4 >> 7
ld a,(T4)
srl a
srl a
srl a
srl a
srl a
srl a
srl a
ld (T9),a
; T4 = T4 << 1
ld a,(T4)
sla a
ld (T4),a
; T5 = T5 << 1
ld a,(T5)
sla a
ld (T5),a
; T5 = T5 | T9
ld a,(T5)
ld b,a
ld a,(T9)
ld c,a
ld a,b
or c
ld (T5),a
; T1 = T1 >> 1
ld a,(T1)
srl a
ld (T1),a
; T0 = T0 - 1
ld a,(T0)
sub 1
ld (T0),a
jp byte_interpolation_L4
byte_interpolation_L6:
; T2 = 0
ld a,0
ld (T2),a
; while T7 != 0:
byte_interpolation_L13:
ld a,(T7)
cp 0
jp nz,byte_interpolation_L14
jp byte_interpolation_L15
byte_interpolation_L14:
; T8 = 0
ld a,0
ld (T8),a
; if T6 < 255:
ld a,(T6)
cp 255
jp c,byte_interpolation_L16
jp byte_interpolation_L17
byte_interpolation_L16:
; T8 = 1
ld a,1
ld (T8),a
jp byte_interpolation_L18
byte_interpolation_L17:
byte_interpolation_L18:
; T6 = T6 - 255
ld a,(T6)
sub 255
ld (T6),a
; T7 = T7 - T8
ld a,(T7)
ld b,a
ld a,(T8)
ld c,a
ld a,b
sub c
ld (T7),a
; T2 = T2 + 1
ld a,(T2)
add a,1
ld (T2),a
jp byte_interpolation_L13
byte_interpolation_L15:
; if T6 == 255:
ld a,(T6)
cp 255
jp z,byte_interpolation_L19
jp byte_interpolation_L20
byte_interpolation_L19:
; T2 = T2 + 1
ld a,(T2)
add a,1
ld (T2),a
jp byte_interpolation_L21
byte_interpolation_L20:
byte_interpolation_L21:
; VALUE = START
ld a,(START)
ld (VALUE),a
; if T10 == 0:
ld a,(T10)
cp 0
jp z,byte_interpolation_L22
jp byte_interpolation_L23
byte_interpolation_L22:
; VALUE = VALUE + T2
ld a,(VALUE)
ld b,a
ld a,(T2)
ld c,a
ld a,b
add a,c
ld (VALUE),a
jp byte_interpolation_L24
byte_interpolation_L23:
; VALUE = VALUE - T2
ld a,(VALUE)
ld b,a
ld a,(T2)
ld c,a
ld a,b
sub c
ld (VALUE),a
byte_interpolation_L24:
ret
component_end:Machine contract
The shared mathematical field END is bound as ENDPOINT on Spectrum because END is an assembler directive. The field order and arithmetic are unchanged.
AF/BC/DE/HL may change; IX/IY are preserved. A direct CALL needs two return-address stack bytes. The helper makes no nested calls and adds no other stack use. Its named scratch is private workspace, not a pointer, a ROM variable or shared zero-page space that the game may borrow concurrently. The samples use fixed symbol bindings. Scope or rename every label and binding, including the component_end measurement marker, and allocate a separate block for each independent instance. Different helpers can also use common field names, so combining them needs separate namespaces or explicitly renamed bindings. Give each block one mutation owner.
The 48K diagnostic boots through ROM tape loading and USR, disables interrupts and owns the screen. The helper performs no port or screen writes.
Adapt the caller
demo.asm supplies the bindings and include order. exercise.inc first runs table cases, then a separate client retaining state between calls. A game can call the public step entry directly and remove the diagnostic packet and display. Do not copy the diagnostic’s hardware takeover into an existing game loop.
Build with make ASM198X=/path/to/asm198x. The Makefile produces normal, custom, deliberately wrong and repaired programs. Tools must already be installed; the sample downloads nothing.
Bindings and include order
org $8000
CUSTOM equ 0
BROKEN equ 0
COYOTE_STEPS equ 4
BUFFER_STEPS equ 4
TEXT_CAP equ 8
PROPERTY_COUNT equ 16
STREAM_BYTES equ 13
CRC_POLY equ 7
include "caller.inc"
include "exercise.inc"
component_start:
include "component.inc"
include "data.inc"
include "cases.inc"
include "../../physics/rectangle-overlap/display.inc"
code_end:
STATE:
VALUE: defb 0
START: defb 0
ENDPOINT: defb 0
FRACTION: defb 0
T0: defb 0
T1: defb 0
T2: defb 0
T4: defb 0
T5: defb 0
T6: defb 0
T7: defb 0
T8: defb 0
T9: defb 0
T10: defb 0
T11: defb 0
input_ptr: defw 0
output_ptr: defw 0
cases_left: defb 0
ready: defb 0
preview: defs 8,0
OUTPUT: defs 1300,0
end startA client retaining state between calls
preview_rules:
if CUSTOM
; START = 210
ld a,210
ld (START),a
; ENDPOINT = 10
ld a,10
ld (ENDPOINT),a
; FRACTION = 255
ld a,255
ld (FRACTION),a
if BROKEN
; FRACTION = 0
ld a,0
ld (FRACTION),a
endif
call checked_step
call emit_state
ret
else
; START = 10
ld a,10
ld (START),a
; ENDPOINT = 210
ld a,210
ld (ENDPOINT),a
; FRACTION = 128
ld a,128
ld (FRACTION),a
if BROKEN
; FRACTION = 0
ld a,0
ld (FRACTION),a
endif
call checked_step
call emit_state
endif
retCustomise it
Reverse the endpoints and finish exactly at the destination. The maintained custom caller changes its inputs or client sequence rather than hiding a different implementation behind the same label. Compare every state of the two clients, not only their final display.
Custom client selection
org $8000
CUSTOM equ 1
BROKEN equ 0
COYOTE_STEPS equ 2
BUFFER_STEPS equ 2
TEXT_CAP equ 4
PROPERTY_COUNT equ 16
STREAM_BYTES equ 13
CRC_POLY equ 49
include "caller.inc"
include "exercise.inc"
component_start:
include "component.inc"
include "data.inc"
include "cases.inc"
include "../../physics/rectangle-overlap/display.inc"
code_end:
STATE:
VALUE: defb 0
START: defb 0
ENDPOINT: defb 0
FRACTION: defb 0
T0: defb 0
T1: defb 0
T2: defb 0
T4: defb 0
T5: defb 0
T6: defb 0
T7: defb 0
T8: defb 0
T9: defb 0
T10: defb 0
T11: defb 0
input_ptr: defw 0
output_ptr: defw 0
cases_left: defb 0
ready: defb 0
preview: defs 8,0
OUTPUT: defs 1300,0
end startThe custom diagnostic row is 0A D2 0A FF 00 00 00 00. The full client trace in the source explains how it gets there.
Mistake and repair
The wrong caller sends a fraction of zero on every update. The interpolation stays at its starting point. Advance the fraction separately, and retain the original endpoints while that transition is in progress.
The BROKEN branch lives in the sequential client, not the reusable helper. wrong.asm selects it; repaired.asm restores the normal call sequence. The repaired executable matches the normal program (for Spectrum, compare loaded CODE rather than the tape filename).
Select the deliberately wrong client
org $8000
CUSTOM equ 0
BROKEN equ 1
COYOTE_STEPS equ 4
BUFFER_STEPS equ 4
TEXT_CAP equ 8
PROPERTY_COUNT equ 16
STREAM_BYTES equ 13
CRC_POLY equ 7
include "caller.inc"
include "exercise.inc"
component_start:
include "component.inc"
include "data.inc"
include "cases.inc"
include "../../physics/rectangle-overlap/display.inc"
code_end:
STATE:
VALUE: defb 0
START: defb 0
ENDPOINT: defb 0
FRACTION: defb 0
T0: defb 0
T1: defb 0
T2: defb 0
T4: defb 0
T5: defb 0
T6: defb 0
T7: defb 0
T8: defb 0
T9: defb 0
T10: defb 0
T11: defb 0
input_ptr: defw 0
output_ptr: defw 0
cases_left: defb 0
ready: defb 0
preview: defs 8,0
OUTPUT: defs 1300,0
end start
Cost and alternatives
The measured helper extent is 451 code bytes; public state is 4 bytes and private scratch is 11 bytes. There are no immutable helper tables. Caller data, the test cases, return-address stack, alignment and display buffers cost additional space. These are assembled sizes, not cycle measurements.
Eight product stages followed by up to 255 subtraction stages. A /256 scale is cheaper but needs an explicit final-endpoint policy. A wider fixed-point interpolation or native 68000 multiply/divide can trade code for faster updates.
This computes a position for a supplied fraction; it does not own a clock or easing curve. Replacing START with the previous output every frame creates a different, asymptotic motion. Descending values deliberately use start-relative rounding rather than floor of the final signed expression.
Execution evidence
Four variants run on 48K PAL ROM tape load and USR, using Asm198x 0.0.72, Emu198x 0.44.2. Each executes 64 boundary/varied/error table cases, dirty initialisation and the separate retained-state client. An independent mathematical/container model checks every public byte after every call. This is bounded example coverage, not exhaustive correctness for every possible state.
The records retain loaded immutable code, completion, register sentinels, full packets, source/tool/firmware hashes and captures. The public gate validates these retained observations and rejects altered evidence; it does not run restricted firmware. No firmware is distributed. The eight displayed bytes are the first eight public fields, zero-padded when shorter; the packet includes every field.
Where it fits
Rational tick division: A scheduling routine can decide when to advance the transition; interpolation decides which position that progress represents.