A world can be larger than the screen even when the drawing routine expects byte-sized screen coordinates.
Use it in a project
World and camera positions are unsigned little-endian words. WIDTH/HEIGHT are 1–255 logical units. A point is visible only when world−camera is nonnegative on each axis and strictly below the corresponding extent. Return byte SCREEN_X/Y and VISIBLE=1; hidden points return zero coordinates. Zero extents return VALID=0. Preserve inputs.
Include component.inc once (MOS callers include the shared 6502 implementation through it). Reserve the public fields in this exact order: SCREEN_X, SCREEN_Y, VISIBLE, VALID, WORLD_X_LO, WORLD_X_HI, WORLD_Y_LO, WORLD_Y_HI, CAMERA_X_LO, CAMERA_X_HI, CAMERA_Y_LO, CAMERA_Y_HI, WIDTH, HEIGHT. They occupy 14 contiguous bytes. Also reserve the private workspace: T0, T1, T2, T3 (4 bytes). Array names in the explanation refer to the numbered consecutive bindings, such as C0, C1 and so on.
Call viewport_world_transform_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 viewport_world_transform_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 | world/camera words and WIDTH/HEIGHT |
| Read after service | SCREEN_X/Y, VISIBLE and VALID |
First reject negative differences with full-word comparisons. Subtract each low byte and borrow into its high byte, then accept only a zero high difference and a low difference inside the viewport.
Reusable initialisation and service
; SPDX-License-Identifier: MIT
; Project World Points into a Viewport. See README.md for the byte interface and ownership.
; init clears the public fields and private workspace; set inputs afterwards.
viewport_world_transform_init:
lda #0
sta SCREEN_X
sta SCREEN_Y
sta VISIBLE
sta VALID
sta WORLD_X_LO
sta WORLD_X_HI
sta WORLD_Y_LO
sta WORLD_Y_HI
sta CAMERA_X_LO
sta CAMERA_X_HI
sta CAMERA_Y_LO
sta CAMERA_Y_HI
sta WIDTH
sta HEIGHT
sta T0
sta T1
sta T2
sta T3
rts
viewport_world_transform_step:
; SCREEN_X = 0
lda #0
sta SCREEN_X
; SCREEN_Y = 0
lda #0
sta SCREEN_Y
; VISIBLE = 0
lda #0
sta VISIBLE
; VALID = 0
lda #0
sta VALID
; if WIDTH == 0:
lda WIDTH
cmp #0
beq viewport_world_transform_L4
viewport_world_transform_L5:
jmp viewport_world_transform_L2
viewport_world_transform_L4:
jmp viewport_world_transform_L1
viewport_world_transform_L1:
; return
rts
jmp viewport_world_transform_L3
viewport_world_transform_L2:
viewport_world_transform_L3:
; if HEIGHT == 0:
lda HEIGHT
cmp #0
beq viewport_world_transform_L9
viewport_world_transform_L10:
jmp viewport_world_transform_L7
viewport_world_transform_L9:
jmp viewport_world_transform_L6
viewport_world_transform_L6:
; return
rts
jmp viewport_world_transform_L8
viewport_world_transform_L7:
viewport_world_transform_L8:
; VALID = 1
lda #1
sta VALID
; if WORLD_X_HI < CAMERA_X_HI:
lda WORLD_X_HI
cmp CAMERA_X_HI
bcc viewport_world_transform_L14
viewport_world_transform_L15:
jmp viewport_world_transform_L12
viewport_world_transform_L14:
jmp viewport_world_transform_L11
viewport_world_transform_L11:
; return
rts
jmp viewport_world_transform_L13
viewport_world_transform_L12:
viewport_world_transform_L13:
; if WORLD_X_HI == CAMERA_X_HI:
lda WORLD_X_HI
cmp CAMERA_X_HI
beq viewport_world_transform_L19
viewport_world_transform_L20:
jmp viewport_world_transform_L17
viewport_world_transform_L19:
jmp viewport_world_transform_L16
viewport_world_transform_L16:
; if WORLD_X_LO < CAMERA_X_LO:
lda WORLD_X_LO
cmp CAMERA_X_LO
bcc viewport_world_transform_L24
viewport_world_transform_L25:
jmp viewport_world_transform_L22
viewport_world_transform_L24:
jmp viewport_world_transform_L21
viewport_world_transform_L21:
; return
rts
jmp viewport_world_transform_L23
viewport_world_transform_L22:
viewport_world_transform_L23:
jmp viewport_world_transform_L18
viewport_world_transform_L17:
viewport_world_transform_L18:
; if WORLD_Y_HI < CAMERA_Y_HI:
lda WORLD_Y_HI
cmp CAMERA_Y_HI
bcc viewport_world_transform_L29
viewport_world_transform_L30:
jmp viewport_world_transform_L27
viewport_world_transform_L29:
jmp viewport_world_transform_L26
viewport_world_transform_L26:
; return
rts
jmp viewport_world_transform_L28
viewport_world_transform_L27:
viewport_world_transform_L28:
; if WORLD_Y_HI == CAMERA_Y_HI:
lda WORLD_Y_HI
cmp CAMERA_Y_HI
beq viewport_world_transform_L34
viewport_world_transform_L35:
jmp viewport_world_transform_L32
viewport_world_transform_L34:
jmp viewport_world_transform_L31
viewport_world_transform_L31:
; if WORLD_Y_LO < CAMERA_Y_LO:
lda WORLD_Y_LO
cmp CAMERA_Y_LO
bcc viewport_world_transform_L39
viewport_world_transform_L40:
jmp viewport_world_transform_L37
viewport_world_transform_L39:
jmp viewport_world_transform_L36
viewport_world_transform_L36:
; return
rts
jmp viewport_world_transform_L38
viewport_world_transform_L37:
viewport_world_transform_L38:
jmp viewport_world_transform_L33
viewport_world_transform_L32:
viewport_world_transform_L33:
; T0 = WORLD_X_LO - CAMERA_X_LO
lda WORLD_X_LO
sec
sbc CAMERA_X_LO
sta T0
; T1 = WORLD_X_HI - CAMERA_X_HI
lda WORLD_X_HI
sec
sbc CAMERA_X_HI
sta T1
; if WORLD_X_LO < CAMERA_X_LO:
lda WORLD_X_LO
cmp CAMERA_X_LO
bcc viewport_world_transform_L44
viewport_world_transform_L45:
jmp viewport_world_transform_L42
viewport_world_transform_L44:
jmp viewport_world_transform_L41
viewport_world_transform_L41:
; T1 = T1 - 1
lda T1
sec
sbc #1
sta T1
jmp viewport_world_transform_L43
viewport_world_transform_L42:
viewport_world_transform_L43:
; if T1 != 0:
lda T1
cmp #0
bne viewport_world_transform_L49
viewport_world_transform_L50:
jmp viewport_world_transform_L47
viewport_world_transform_L49:
jmp viewport_world_transform_L46
viewport_world_transform_L46:
; return
rts
jmp viewport_world_transform_L48
viewport_world_transform_L47:
viewport_world_transform_L48:
; if T0 >= WIDTH:
lda T0
cmp WIDTH
bcs viewport_world_transform_L54
viewport_world_transform_L55:
jmp viewport_world_transform_L52
viewport_world_transform_L54:
jmp viewport_world_transform_L51
viewport_world_transform_L51:
; return
rts
jmp viewport_world_transform_L53
viewport_world_transform_L52:
viewport_world_transform_L53:
; T2 = WORLD_Y_LO - CAMERA_Y_LO
lda WORLD_Y_LO
sec
sbc CAMERA_Y_LO
sta T2
; T3 = WORLD_Y_HI - CAMERA_Y_HI
lda WORLD_Y_HI
sec
sbc CAMERA_Y_HI
sta T3
; if WORLD_Y_LO < CAMERA_Y_LO:
lda WORLD_Y_LO
cmp CAMERA_Y_LO
bcc viewport_world_transform_L59
viewport_world_transform_L60:
jmp viewport_world_transform_L57
viewport_world_transform_L59:
jmp viewport_world_transform_L56
viewport_world_transform_L56:
; T3 = T3 - 1
lda T3
sec
sbc #1
sta T3
jmp viewport_world_transform_L58
viewport_world_transform_L57:
viewport_world_transform_L58:
; if T3 != 0:
lda T3
cmp #0
bne viewport_world_transform_L64
viewport_world_transform_L65:
jmp viewport_world_transform_L62
viewport_world_transform_L64:
jmp viewport_world_transform_L61
viewport_world_transform_L61:
; return
rts
jmp viewport_world_transform_L63
viewport_world_transform_L62:
viewport_world_transform_L63:
; if T2 >= HEIGHT:
lda T2
cmp HEIGHT
bcs viewport_world_transform_L69
viewport_world_transform_L70:
jmp viewport_world_transform_L67
viewport_world_transform_L69:
jmp viewport_world_transform_L66
viewport_world_transform_L66:
; return
rts
jmp viewport_world_transform_L68
viewport_world_transform_L67:
viewport_world_transform_L68:
; SCREEN_X = T0
lda T0
sta SCREEN_X
; SCREEN_Y = T2
lda T2
sta SCREEN_Y
; VISIBLE = 1
lda #1
sta VISIBLE
rts
component_end:Machine contract
A/X/status may change; Y and decimal mode are preserved. Use CLD for binary arithmetic. 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 diagnostic PRG owns screen, font and colour RAM and disables interrupts; it does not return to BASIC. The reusable helper does none of those things.
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
SCREEN_X=$80
SCREEN_Y=$81
VISIBLE=$82
VALID=$83
WORLD_X_LO=$84
WORLD_X_HI=$85
WORLD_Y_LO=$86
WORLD_Y_HI=$87
CAMERA_X_LO=$88
CAMERA_X_HI=$89
CAMERA_Y_LO=$8a
CAMERA_Y_HI=$8b
WIDTH=$8c
HEIGHT=$8d
T0=$8e
T1=$8f
T2=$90
T3=$91
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$c000
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
!source "caller.inc"
!source "exercise.inc"
component_start:
!source "component.inc"
!source "data.inc"
!source "cases.inc"
hex_font:
!byte 0,0,0,0,0,0,0,0,0,56,40,40,40,56,0,0,0,16,48,16,16,56,0,0,0,56,8,56,32,56,0,0,0,56,8,56,8,56,0,0,0,40,40,56,8,8,0,0,0,56,32,56,8,56,0,0,0,56,32,56,40,56,0,0,0,56,8,8,8,8,0,0,0,56,40,56,40,56,0,0,0,56,40,56,8,56,0,0,0,16,40,56,40,40,0,0,0,48,40,48,40,48,0,0,0,56,32,32,32,56,0,0,0,48,40,40,40,48,0,0,0,56,32,48,32,56,0,0,0,56,32,48,32,32,0,0
code_end:A client retaining state between calls
preview_rules:
!if CUSTOM {
; WORLD_X_LO = 255
lda #255
sta WORLD_X_LO
; WORLD_X_HI = 255
lda #255
sta WORLD_X_HI
; WORLD_Y_LO = 255
lda #255
sta WORLD_Y_LO
; WORLD_Y_HI = 255
lda #255
sta WORLD_Y_HI
; CAMERA_X_LO = 254
lda #254
sta CAMERA_X_LO
; CAMERA_X_HI = 255
lda #255
sta CAMERA_X_HI
; CAMERA_Y_LO = 254
lda #254
sta CAMERA_Y_LO
; CAMERA_Y_HI = 255
lda #255
sta CAMERA_Y_HI
; WIDTH = 2
lda #2
sta WIDTH
; HEIGHT = 2
lda #2
sta HEIGHT
!if BROKEN {
; WORLD_X_HI = 0
lda #0
sta WORLD_X_HI
}
jsr checked_step
jsr emit_state
rts
} else {
; WORLD_X_LO = 5
lda #5
sta WORLD_X_LO
; WORLD_X_HI = 1
lda #1
sta WORLD_X_HI
; WORLD_Y_LO = 10
lda #10
sta WORLD_Y_LO
; WORLD_Y_HI = 1
lda #1
sta WORLD_Y_HI
; CAMERA_X_LO = 250
lda #250
sta CAMERA_X_LO
; CAMERA_X_HI = 0
lda #0
sta CAMERA_X_HI
; CAMERA_Y_LO = 0
lda #0
sta CAMERA_Y_LO
; CAMERA_Y_HI = 1
lda #1
sta CAMERA_Y_HI
; WIDTH = 32
lda #32
sta WIDTH
; HEIGHT = 24
lda #24
sta HEIGHT
!if BROKEN {
; WORLD_X_HI = 0
lda #0
sta WORLD_X_HI
}
jsr checked_step
jsr emit_state
}
rtsCustomise it
Project a point near the maximum word coordinate into a two-unit viewport. 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
SCREEN_X=$80
SCREEN_Y=$81
VISIBLE=$82
VALID=$83
WORLD_X_LO=$84
WORLD_X_HI=$85
WORLD_Y_LO=$86
WORLD_Y_HI=$87
CAMERA_X_LO=$88
CAMERA_X_HI=$89
CAMERA_Y_LO=$8a
CAMERA_Y_HI=$8b
WIDTH=$8c
HEIGHT=$8d
T0=$8e
T1=$8f
T2=$90
T3=$91
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$c000
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
!source "caller.inc"
!source "exercise.inc"
component_start:
!source "component.inc"
!source "data.inc"
!source "cases.inc"
hex_font:
!byte 0,0,0,0,0,0,0,0,0,56,40,40,40,56,0,0,0,16,48,16,16,56,0,0,0,56,8,56,32,56,0,0,0,56,8,56,8,56,0,0,0,40,40,56,8,8,0,0,0,56,32,56,8,56,0,0,0,56,32,56,40,56,0,0,0,56,8,8,8,8,0,0,0,56,40,56,40,56,0,0,0,56,40,56,8,56,0,0,0,16,40,56,40,40,0,0,0,48,40,48,40,48,0,0,0,56,32,32,32,56,0,0,0,48,40,40,40,48,0,0,0,56,32,48,32,56,0,0,0,56,32,48,32,32,0,0
code_end:The custom diagnostic row is 01 01 01 01 FF FF FF FF. The full client trace in the source explains how it gets there.
Mistake and repair
The wrong caller drops the world X high byte. A point just beyond 255 appears behind the camera instead of eleven units to its right. Preserve both bytes through the coordinate transform.
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
SCREEN_X=$80
SCREEN_Y=$81
VISIBLE=$82
VALID=$83
WORLD_X_LO=$84
WORLD_X_HI=$85
WORLD_Y_LO=$86
WORLD_Y_HI=$87
CAMERA_X_LO=$88
CAMERA_X_HI=$89
CAMERA_Y_LO=$8a
CAMERA_Y_HI=$8b
WIDTH=$8c
HEIGHT=$8d
T0=$8e
T1=$8f
T2=$90
T3=$91
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$c000
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
!source "caller.inc"
!source "exercise.inc"
component_start:
!source "component.inc"
!source "data.inc"
!source "cases.inc"
hex_font:
!byte 0,0,0,0,0,0,0,0,0,56,40,40,40,56,0,0,0,16,48,16,16,56,0,0,0,56,8,56,32,56,0,0,0,56,8,56,8,56,0,0,0,40,40,56,8,8,0,0,0,56,32,56,8,56,0,0,0,56,32,56,40,56,0,0,0,56,8,8,8,8,0,0,0,56,40,56,40,56,0,0,0,56,40,56,8,56,0,0,0,16,40,56,40,40,0,0,0,48,40,48,40,48,0,0,0,56,32,32,32,56,0,0,0,48,40,40,40,48,0,0,0,56,32,48,32,56,0,0,0,56,32,48,32,32,0,0
code_end:
Cost and alternatives
The measured helper extent is 334 code bytes; public state is 14 bytes and private scratch is 4 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.
Constant work with no division. Subtracting in the world representation before narrowing avoids byte wrap; fixed-point world coordinates additionally need an explicit fractional-bit conversion.
This projects points, not partly visible sprites or rectangles. Extents are at most 255, so a 256-unit viewport needs a wider extent representation. Camera coordinates do not wrap and the routine does not write display registers.
Execution evidence
Four variants run on PAL stock-ROM PRG, 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
Rectangle clipping: After projecting an object’s origin, clip its visible shape with the appropriate signed or wider rectangle representation.