Decode Bounded RLE Data on Amiga | Pattern Library

Repeated tiles or pixels can be stored as a count followed by a value. Decoding is small, but trusting a damaged run count can overwrite the next object in RAM. This version checks both ends and tells the caller exactly how much output was produced.

Amiga shows the working diagnostic row 06 00 00 06 08 41 41 41. — A native completed caller shows its state as hexadecimal bytes. The field order below explains the row; the full packet retains every call.

Include, initialise and call

Reserve WRITTEN, ERROR, INPUT_START, INPUT_END, OUTPUT_LIMIT, BUF0, BUF1, BUF2, BUF3, BUF4, BUF5, BUF6, BUF7 as 13 contiguous private bytes in that order. Include the helper once. Call bounded_rle_init at the intended reset boundary: it clears every named byte, including input fields. Set the starting values afterwards, then call bounded_rle_step for each intended service.

Initialise once, set the selected encoded span and available output length, then service. Check ERROR before accepting an asset as complete. On a decoding error the buffer contains a valid decoded prefix of length WRITTEN; it is not rolled back. Bytes after that prefix are preserved. A consumer that wants an all-or-nothing asset should decode into staging memory and commit only on success.

INPUT_START and INPUT_END are byte offsets into caller-owned rle_stream, with INPUT_START ≤ INPUT_END ≤ STREAM_BYTES. OUTPUT_LIMIT is 0–8 for the reserved eight-byte output buffer. Step replaces WRITTEN and ERROR, preserves the input parameters and decodes count/value pairs. ERROR 0 means the selected input span finished; 1 means invalid input/output bounds; 2 means a truncated pair; 3 means a zero run; 4 means output capacity was reached before the selected stream finished. WRITTEN counts only bytes actually stored.

Reusable initialisation and service

component.inc

; SPDX-License-Identifier: MIT
; Decode Bounded RLE Data. Contiguous private bytes: WRITTEN, ERROR, INPUT_START, INPUT_END, OUTPUT_LIMIT, BUF0, BUF1, BUF2, BUF3, BUF4, BUF5, BUF6, BUF7.
; init clears all fields; set inputs afterwards. No I/O, waits or IRQ ownership.
; D0-D3/A0-A1/CCR change; D4-D7/A2-A6 survive.
bounded_rle_init:
    clr.b WRITTEN
    clr.b ERROR
    clr.b INPUT_START
    clr.b INPUT_END
    clr.b OUTPUT_LIMIT
    clr.b BUF0
    clr.b BUF1
    clr.b BUF2
    clr.b BUF3
    clr.b BUF4
    clr.b BUF5
    clr.b BUF6
    clr.b BUF7
    rts
bounded_rle_step:
    clr.b WRITTEN
    clr.b ERROR
    cmp.b #STREAM_BYTES,INPUT_END
    bhi.s rle_bounds
    move.b INPUT_START,d0
    cmp.b INPUT_END,d0
    bhi.s rle_bounds
    cmp.b #8,OUTPUT_LIMIT
    bls.s rle_start
rle_bounds:
    move.b #1,ERROR
    rts
rle_start:
    moveq #0,d0
    move.b INPUT_START,d0
    moveq #0,d3
    lea rle_stream,a0
    lea BUF0,a1
rle_pair:
    cmp.b INPUT_END,d0
    beq.s rle_done
    move.w d0,d1
    addq.w #1,d1
    cmp.b INPUT_END,d1
    bhs.s rle_truncated
    moveq #0,d1
    move.b 0(a0,d0.w),d1
    beq.s rle_zero
    addq.w #1,d0
    move.b 0(a0,d0.w),d2
    addq.w #1,d0
rle_copy:
    cmp.b OUTPUT_LIMIT,d3
    bhs.s rle_full
    move.b d2,0(a1,d3.w)
    addq.w #1,d3
    subq.b #1,d1
    bne.s rle_copy
    bra.s rle_pair
rle_full:
    move.b #4,ERROR
    bra.s rle_done
rle_truncated:
    move.b #2,ERROR
    bra.s rle_done
rle_zero:
    move.b #3,ERROR
rle_done:
    move.b d3,WRITTEN
    rts
component_end:

Caller-owned immutable lookup/encoded data

data.inc

data_start:
rle_stream:
    dc.b 3,65,2,66,1,67,0,88,5,68,1,69,2
data_end:

State, registers and ownership

Five control/input/output bytes followed by BUF0–BUF7. The sample has thirteen immutable input bytes, including malformed examples. Count zero is rejected; there is no terminator convention or implicit end beyond INPUT_END. A zero-length selected span succeeds with zero output. The routine can stop partway through a run when capacity is exhausted.

D0–D3/A0–A1/CCR may change; D4–D7/A2–A6 survive. A direct BSR/JSR needs four return-address stack bytes.

The implementation binds fixed symbols and has one mutation owner. Independent users need separate state blocks and scoped/renamed labels, including routine labels; sharing the same bindings means sharing the state. Do not let an interrupt and the main loop mutate the same block without an explicit ownership policy.

The bootable caller takes over Copper/bitplane/interrupt/DMA resources and explicitly disarms all eight sprites. It does not restore Workbench. These are caller presentation choices, not dependencies of the reusable helper.

A caller you can adapt

The buildable program supplies bindings and include order. Its separate client retains state between calls. checked_step calls the public bounded_rle_step entry and checks register sentinels; emit_state records diagnostics. Your game can call the public entry directly, remove the diagnostics and consume the documented outputs.

Bindings, buildable caller and include order

demo.asm

    section code,code_c
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"
    even
    include "display.inc"
    include "../../framework/turn-deadline/font.inc"
code_end:
STATE:
WRITTEN: dc.b 0
ERROR: dc.b 0
INPUT_START: dc.b 0
INPUT_END: dc.b 0
OUTPUT_LIMIT: dc.b 0
BUF0: dc.b 0
BUF1: dc.b 0
BUF2: dc.b 0
BUF3: dc.b 0
BUF4: dc.b 0
BUF5: dc.b 0
BUF6: dc.b 0
BUF7: dc.b 0
    even
ready: dc.w 0
preview: dcb.b 8,0
OUTPUT: dcb.b 1300,0
    even
signature: dc.b "198XPLAYTOOLS00",0
    even
copperlist:
    dc.w $08e,$2c81,$090,$2cc1,$092,$0038,$094,$00d0
    dc.w $100,$1200,$102,0,$104,0,$108,0,$10a,0
    dc.w $180,$012,$182,$fff
copbpl:
    dc.w $0e0,0,$0e2,0
    dc.w $ffff,$fffe
plane: dcb.b 10240,0

A separate client retaining state between calls

exercise.inc, excerpt

preview_rules:
    ifne CUSTOM
    move.b #0,INPUT_START
    move.b #6,INPUT_END
    move.b #5,OUTPUT_LIMIT
    ifne BROKEN
    bsr checked_step
    move.b OUTPUT_LIMIT,WRITTEN
    else
    bsr checked_step
    endif
    bsr emit_state
    else
    move.b #0,INPUT_START
    move.b #6,INPUT_END
    move.b #8,OUTPUT_LIMIT
    ifne BROKEN
    bsr checked_step
    move.b OUTPUT_LIMIT,WRITTEN
    else
    bsr checked_step
    endif
    bsr emit_state
    endif
    rts

The display fields are WRITTEN, ERROR, INPUT_START, INPUT_END, OUTPUT_LIMIT, BUF0, BUF1, BUF2; later state bytes are retained in the full packet. Each is one hexadecimal byte. The normal row is 06 00 00 06 08 41 41 41. This is a completed state observation, not a recording of an actual character jumping, a camera scrolling or an asset being displayed.

Make it your own

The normal caller decodes the first six input bytes into AAABBC, six output bytes. The custom caller offers only five output slots: AAABB is produced and ERROR 4 reports the unfinished selected stream. Treating capacity as the amount written would hide the normal caller’s two unused slots.

Maintained custom configuration or caller

custom.asm

    section code,code_c
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"
    even
    include "display.inc"
    include "../../framework/turn-deadline/font.inc"
code_end:
STATE:
WRITTEN: dc.b 0
ERROR: dc.b 0
INPUT_START: dc.b 0
INPUT_END: dc.b 0
OUTPUT_LIMIT: dc.b 0
BUF0: dc.b 0
BUF1: dc.b 0
BUF2: dc.b 0
BUF3: dc.b 0
BUF4: dc.b 0
BUF5: dc.b 0
BUF6: dc.b 0
BUF7: dc.b 0
    even
ready: dc.w 0
preview: dcb.b 8,0
OUTPUT: dcb.b 1300,0
    even
signature: dc.b "198XPLAYTOOLS00",0
    even
copperlist:
    dc.w $08e,$2c81,$090,$2cc1,$092,$0038,$094,$00d0
    dc.w $100,$1200,$102,0,$104,0,$108,0,$10a,0
    dc.w $180,$012,$182,$fff
copbpl:
    dc.w $0e0,0,$0e2,0
    dc.w $ffff,$fffe
plane: dcb.b 10240,0

The custom row is 05 04 00 06 05 41 41 41. These records qualify the named builds and inputs; another layout, format or input domain needs explicit bounds and fresh execution evidence.

Common mistake and repair

The wrong client replaces WRITTEN with OUTPUT_LIMIT after decoding. The normal six-byte asset is now advertised as eight bytes, including two bytes the decoder never produced. Publish the returned length, and check the returned error; capacity is not output length.

Select the deliberately wrong client

wrong.asm

    section code,code_c
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"
    even
    include "display.inc"
    include "../../framework/turn-deadline/font.inc"
code_end:
STATE:
WRITTEN: dc.b 0
ERROR: dc.b 0
INPUT_START: dc.b 0
INPUT_END: dc.b 0
OUTPUT_LIMIT: dc.b 0
BUF0: dc.b 0
BUF1: dc.b 0
BUF2: dc.b 0
BUF3: dc.b 0
BUF4: dc.b 0
BUF5: dc.b 0
BUF6: dc.b 0
BUF7: dc.b 0
    even
ready: dc.w 0
preview: dcb.b 8,0
OUTPUT: dcb.b 1300,0
    even
signature: dc.b "198XPLAYTOOLS00",0
    even
copperlist:
    dc.w $08e,$2c81,$090,$2cc1,$092,$0038,$094,$00d0
    dc.w $100,$1200,$102,0,$104,0,$108,0,$10a,0
    dc.w $180,$012,$182,$fff
copbpl:
    dc.w $0e0,0,$0e2,0
    dc.w $ffff,$fffe
plane: dcb.b 10240,0

Amiga shows the deliberate fault row 08 00 00 06 08 41 41 41. — The wrong client completes with 08 00 00 06 08 41 41 41. Its code and the explanation above identify the cause; the capture observes the result.

The BROKEN branch is visible in the client. repaired.asm restores the normal selection; its executable matches demo exactly. Spectrum tape filenames may differ while loaded CODE remains identical. The fault is a labelled experiment, not a suggested alternative.

Cost, limits and verification

The measured layout has 234 code bytes, 13 immutable data bytes and 13 private state bytes. Alignment, stack usage, diagnostic tables and display machinery are additional. The extents come from the loaded program’s symbols, not from counting source lines.

Work is bounded by the selected input span and output capacity. Each pair consumes two input bytes; each produced byte advances the output count. The qualified output has at most eight stores, with no allocation or hidden display upload. Compression trades encoded storage against decode work and may make alternating data larger.

This is a local classic count/value codec example, not a new project-wide asset format. Longer assets need an appropriately sized output span and possibly wider offsets, plus independently checked bounds. Packed literals, streaming continuation and precompressed build-tool assets are separate extensions. Do not turn zero runs into an unchecked infinite loop or infer success from a full buffer.

Four native runs use A500 OCS PAL with Kickstart 1.3 and an OFS cold-boot disk; Asm198x 0.0.72 and Emu198x 0.44.2, with Build198x 0.2.9 for disk mastering. Each checks 64 boundary/varied/error cases, dirty initialisation and every state of a separate sequential client against an independent integer model. This is not exhaustive coverage of every possible byte combination. Source/tool/firmware hashes, immutable loaded code/data, native startup/completion, preserved-register sentinels, helper/data sizes, screenshot bytes/pixels and exact repair are checked. Deliberately altered observations must fail. Firmware is hashed, never distributed.

Source and native evidence.