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 END at its two endpoints. Return START+floor((END−START)×FRACTION/255) when ascending; when descending, subtract floor((START−END)×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, END, 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, END 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:
lda #0
sta VALUE
sta START
sta END
sta FRACTION
sta T0
sta T1
sta T2
sta T4
sta T5
sta T6
sta T7
sta T8
sta T9
sta T10
sta T11
rts
byte_interpolation_step:
; T10 = 0
lda #0
sta T10
; if END >= START:
lda END
cmp START
bcs byte_interpolation_L4
byte_interpolation_L5:
jmp byte_interpolation_L2
byte_interpolation_L4:
jmp byte_interpolation_L1
byte_interpolation_L1:
; T11 = END - START
lda END
sec
sbc START
sta T11
jmp byte_interpolation_L3
byte_interpolation_L2:
; T11 = START - END
lda START
sec
sbc END
sta T11
; T10 = 1
lda #1
sta T10
byte_interpolation_L3:
; T4 = T11
lda T11
sta T4
; T5 = 0
lda #0
sta T5
; T1 = FRACTION
lda FRACTION
sta T1
; T6 = 0
lda #0
sta T6
; T7 = 0
lda #0
sta T7
; T0 = 8
lda #8
sta T0
; while T0 != 0:
byte_interpolation_L6:
lda T0
cmp #0
bne byte_interpolation_L9
byte_interpolation_L10:
jmp byte_interpolation_L8
byte_interpolation_L9:
jmp byte_interpolation_L7
byte_interpolation_L7:
; T9 = T1 & 1
lda T1
and #1
sta T9
; if T9 != 0:
lda T9
cmp #0
bne byte_interpolation_L14
byte_interpolation_L15:
jmp byte_interpolation_L12
byte_interpolation_L14:
jmp byte_interpolation_L11
byte_interpolation_L11:
; T8 = T6
lda T6
sta T8
; T6 = T6 + T4
lda T6
clc
adc T4
sta T6
; T9 = 0
lda #0
sta T9
; if T6 < T8:
lda T6
cmp T8
bcc byte_interpolation_L19
byte_interpolation_L20:
jmp byte_interpolation_L17
byte_interpolation_L19:
jmp byte_interpolation_L16
byte_interpolation_L16:
; T9 = 1
lda #1
sta T9
jmp byte_interpolation_L18
byte_interpolation_L17:
byte_interpolation_L18:
; T7 = T7 + T5
lda T7
clc
adc T5
sta T7
; T7 = T7 + T9
lda T7
clc
adc T9
sta T7
jmp byte_interpolation_L13
byte_interpolation_L12:
byte_interpolation_L13:
; T9 = T4 >> 7
lda T4
lsr
lsr
lsr
lsr
lsr
lsr
lsr
sta T9
; T4 = T4 << 1
lda T4
asl
sta T4
; T5 = T5 << 1
lda T5
asl
sta T5
; T5 = T5 | T9
lda T5
ora T9
sta T5
; T1 = T1 >> 1
lda T1
lsr
sta T1
; T0 = T0 - 1
lda T0
sec
sbc #1
sta T0
jmp byte_interpolation_L6
byte_interpolation_L8:
; T2 = 0
lda #0
sta T2
; while T7 != 0:
byte_interpolation_L21:
lda T7
cmp #0
bne byte_interpolation_L24
byte_interpolation_L25:
jmp byte_interpolation_L23
byte_interpolation_L24:
jmp byte_interpolation_L22
byte_interpolation_L22:
; T8 = 0
lda #0
sta T8
; if T6 < 255:
lda T6
cmp #255
bcc byte_interpolation_L29
byte_interpolation_L30:
jmp byte_interpolation_L27
byte_interpolation_L29:
jmp byte_interpolation_L26
byte_interpolation_L26:
; T8 = 1
lda #1
sta T8
jmp byte_interpolation_L28
byte_interpolation_L27:
byte_interpolation_L28:
; T6 = T6 - 255
lda T6
sec
sbc #255
sta T6
; T7 = T7 - T8
lda T7
sec
sbc T8
sta T7
; T2 = T2 + 1
lda T2
clc
adc #1
sta T2
jmp byte_interpolation_L21
byte_interpolation_L23:
; if T6 == 255:
lda T6
cmp #255
beq byte_interpolation_L34
byte_interpolation_L35:
jmp byte_interpolation_L32
byte_interpolation_L34:
jmp byte_interpolation_L31
byte_interpolation_L31:
; T2 = T2 + 1
lda T2
clc
adc #1
sta T2
jmp byte_interpolation_L33
byte_interpolation_L32:
byte_interpolation_L33:
; VALUE = START
lda START
sta VALUE
; if T10 == 0:
lda T10
cmp #0
beq byte_interpolation_L39
byte_interpolation_L40:
jmp byte_interpolation_L37
byte_interpolation_L39:
jmp byte_interpolation_L36
byte_interpolation_L36:
; VALUE = VALUE + T2
lda VALUE
clc
adc T2
sta VALUE
jmp byte_interpolation_L38
byte_interpolation_L37:
; VALUE = VALUE - T2
lda VALUE
sec
sbc T2
sta VALUE
byte_interpolation_L38:
rts
component_end:Machine contract
A/X/status may change; Y is preserved. The 2A03 has no decimal arithmetic mode. A direct JSR 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 NROM caller owns PPU setup and background display, with NMI and DMC disabled. Table and packet sizes are bounded to fit the cartridge caller and internal RAM; the helper owns no PPU registers.
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
.segment "HEADER"
.byte "NES",$1a,2,1,0,0,0,0,0,0,0,0,0,0
VALUE=$80
START=$81
END=$82
FRACTION=$83
T0=$84
T1=$85
T2=$86
T4=$87
T5=$88
T6=$89
T7=$8a
T8=$8b
T9=$8c
T10=$8d
T11=$8e
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$0200
preview=OUTPUT+1400
ready=OUTPUT+1408
CUSTOM=0
BROKEN=0
COYOTE_STEPS=4
BUFFER_STEPS=4
TEXT_CAP=8
PROPERTY_COUNT=16
STREAM_BYTES=13
CRC_POLY=7
.include "caller.inc"
.include "exercise.inc"
component_start:
.include "component.inc"
.include "data.inc"
.include "cases.inc"
code_end:
.segment "VECTORS"
.word nmi,reset,irq
.segment "CHARS"
.include "../../input/controller-reading/edges-font.inc"
.res 8192-272,0A client retaining state between calls
preview_rules:
.if CUSTOM
; START = 210
lda #210
sta START
; END = 10
lda #10
sta END
; FRACTION = 255
lda #255
sta FRACTION
.if BROKEN
; FRACTION = 0
lda #0
sta FRACTION
.endif
jsr checked_step
jsr emit_state
rts
.else
; START = 10
lda #10
sta START
; END = 210
lda #210
sta END
; FRACTION = 128
lda #128
sta FRACTION
.if BROKEN
; FRACTION = 0
lda #0
sta FRACTION
.endif
jsr checked_step
jsr emit_state
.endif
rtsCustomise 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
.segment "HEADER"
.byte "NES",$1a,2,1,0,0,0,0,0,0,0,0,0,0
VALUE=$80
START=$81
END=$82
FRACTION=$83
T0=$84
T1=$85
T2=$86
T4=$87
T5=$88
T6=$89
T7=$8a
T8=$8b
T9=$8c
T10=$8d
T11=$8e
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$0200
preview=OUTPUT+1400
ready=OUTPUT+1408
CUSTOM=1
BROKEN=0
COYOTE_STEPS=2
BUFFER_STEPS=2
TEXT_CAP=4
PROPERTY_COUNT=16
STREAM_BYTES=13
CRC_POLY=49
.include "caller.inc"
.include "exercise.inc"
component_start:
.include "component.inc"
.include "data.inc"
.include "cases.inc"
code_end:
.segment "VECTORS"
.word nmi,reset,irq
.segment "CHARS"
.include "../../input/controller-reading/edges-font.inc"
.res 8192-272,0The 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
.segment "HEADER"
.byte "NES",$1a,2,1,0,0,0,0,0,0,0,0,0,0
VALUE=$80
START=$81
END=$82
FRACTION=$83
T0=$84
T1=$85
T2=$86
T4=$87
T5=$88
T6=$89
T7=$8a
T8=$8b
T9=$8c
T10=$8d
T11=$8e
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$0200
preview=OUTPUT+1400
ready=OUTPUT+1408
CUSTOM=0
BROKEN=1
COYOTE_STEPS=4
BUFFER_STEPS=4
TEXT_CAP=8
PROPERTY_COUNT=16
STREAM_BYTES=13
CRC_POLY=7
.include "caller.inc"
.include "exercise.inc"
component_start:
.include "component.inc"
.include "data.inc"
.include "cases.inc"
code_end:
.segment "VECTORS"
.word nmi,reset,irq
.segment "CHARS"
.include "../../input/controller-reading/edges-font.inc"
.res 8192-272,0
Cost and alternatives
The measured helper extent is 336 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 NTSC NROM, background only, DMC/NMI disabled, 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.