AMOSPro AGA Extension

English | Français

AMOSPro AGA Extension extends AMOS Professional on AGA-equipped Commodore Amiga computers, adding screen and palette support, IFF/ILBM loading, double buffering, Blitter and Copper operations, and keyboard and mouse input.

Designed and developed by HWARF, with assistance from ChatGPT (OpenAI) for programming, testing and documentation.

Presentation illustration generated with ChatGPT. This is not an actual extension screenshot.

Separate licenses: source code and technical documentation are under MIT. Artwork, logos, drawings and scans are not covered by MIT, and are not freely reusable. See the visual assets license.

Get started: Installation guide · Six simple AMOS examples.

R27 correction: An initial 0.9.3 candidate was withdrawn before WinUAE because Blitter growth invalidated R23 keyboard/mouse cross-entry BSR offsets and their private-state anchor. The candidate below is the relinked replacement; both native 68000 CPU and strict source export now pass. Incident and fix.

Libraries and tests

• Current library: dist/AMOSPro_AGA.Lib — R27 0.9.3 M12 Safe Blitters, 14,252 bytes, SHA-256 64647f508e5681a09a8c8b51ec9ba8405caf3a52972b5f50034da40a684f0fbe. Gate A native 68000 CPU/CI PASS (403 cases) (final CI 28/28); Gate B interpreted AMOS/WinUAE PASS for the archived 40-swap scenario. Copy/Fill/Clear check Safe themselves without an Aga Text probe or new AMOS tokens. R26 0.9.2 remains a frozen independently WinUAE-PASS archive; R25/R24 and R10 LAST_GOOD unchanged.
• Last-good fallback: dist/AMOSPro_AGA_LAST_GOOD.Lib — R10, intentionally unchanged.
• Validated M6 Blitter tests: R13 Copy, R14 Fill and R15 Clear. Validated M7 Copper tests: R16 Clear, R17 On/Off and R18 raster.
• R27 WinUAE test validated and archived byte-exact: M12_R27_SAFE_BLIT_01.asc, original Git blob 3b3a6d8c120b1ec066669231d382eae6e0e4bd82. 40 completed swaps, Clear/Fill/Copy first-draw successes 14/13/13, temporary rejections 13/13/13, SWAP0 0, SAFEERR 0 SWAPERR 0 DRAWERR 0, CLOSED -1 RESULT 1, normal AMOS return line 167. User saw rectangles blinking. No active .asc in tests/current/. See M12 report; no 50 FPS measurement, exhaustive stress, Compiler or physical AGA validation.
• Earlier binaries: dist/experimental/; historical stable versions: archive/.

Install the library version that matches the test you intend to run. Files on GitHub do not automatically replace libraries installed in AMOS/WinUAE.

Main AMOS commands

Current library API R27 0.9.3 (M5 IFF, M6 Blitter, M7 Copper, and M8 mouse position/buttons/transitions) — all 31 named AMOS commands exported from the AP20 library, including two legacy diagnostics. The table specifies exact call syntax, argument order and return values. Graphics coordinates start at the upper-left (0,0); width and height are dimensions, never end coordinates.

Command	Exact syntax	Parameters and behaviour
Aga Probe	Aga Probe	Legacy no-argument diagnostic instruction. Not recommended as a gameplay API.
Aga Detect	_AGA=Aga Detect	No arguments. Returns a nonzero value when AGA is available; do not assume TRUE is always exactly 1.
Aga Demo	_D=Aga Demo	Legacy no-argument diagnostic function; no stable gameplay return-value contract.
Aga Screen Open	_OK=Aga Screen Open(largeur,hauteur,nbCouleurs,modeID)	Pixel dimensions; nbCouleurs is a colour count, not a bitplane count (indexed modes: 2, 4, 8, 16, 32, 64, 128 or 256). Pass an AmigaOS ModeID, e.g. $00021000 for PAL LowRes. Returns 1 on success, 0 on failure.
Aga Screen Close	Aga Screen Close	No arguments. Closes the AGA screen and releases the associated resources.
Aga Screen Pattern	Aga Screen Pattern	No arguments. Draws the built-in diagnostic pattern.
Aga Double Buffer	_DB=Aga Double Buffer	No arguments. Enables double buffering. Returns 1 on success or 0 on failure.
Aga Swap	_SW=Aga Swap	No arguments. Presents the prepared back buffer. Returns 1 on success or 0 on failure.
Aga Back Fill	Aga Back Fill couleur	One argument: palette colour index used to fill the entire back buffer; e.g. 255 on an 8-bitplane indexed screen.
Aga Pic Info	_V=Aga Pic Info(fichier$,champ)	ILBM file path and field index 0..7 (see reference table below). Returns the selected value, or -1 on error.
Aga Iff Load	_OK=Aga Iff Load(fichier$)	IFF/ILBM file path. Loads pixels and palette onto a compatible AGA screen/buffer. Returns 1 or 0.
Aga Key	_K=Aga Key	No arguments; nonblocking keyboard read. R23: preserves RAWKEY key-down events in a 16-item FIFO shared with the IDCMP mouse dispatcher.
Aga Wait Key	_K=Aga Wait Key	No arguments. Waits for an Intuition-window key and returns a raw key code, which need not be ASCII. R23: uses the shared dispatcher/FIFO; Ctrl+C break handling returned cleanly to AMOS with the Intuition screen closed under WinUAE.
Aga Wait Vbl	Aga Wait Vbl	No arguments. Waits for one vertical blank using WaitTOF. Does nothing if no AGA screen is open.
Aga Blit Copy (R13+, Safe in R27)	_OK=Aga Blit Copy(sourceX,sourceY,destX,destY,largeur,hauteur)	Copies a rectangle within the same back buffer. R27: automatically checks Safe before DMA; returns 0 without copying when the previous front buffer is not yet writable (or arguments/state are invalid), 1 after success. Single nonblocking GetMsg, no ReplyMsg. Gate A CPU PASS, R27 WinUAE NOT TESTED.
Aga Blit Fill (R14+, Safe in R27)	_OK=Aga Blit Fill(x,y,largeur,hauteur,indexCouleur)	Fills the back-buffer rectangle with the fifth-argument palette index. R27: same nonblocking Safe check before the first bitmap DMA; returns 0 without drawing if not ready or invalid. Gate A CPU PASS; WinUAE R27 NOT TESTED.
Aga Blit Clear (R15+, Safe in R27)	_OK=Aga Blit Clear(x,y,largeur,hauteur)	Sets a back-buffer rectangle to palette index 0 (not necessarily RGB black). R27: inherits Fill's nonblocking Safe guard through its native wrapper; returns 0 without clearing when unsafe/invalid. Gate A CPU PASS; WinUAE R27 NOT TESTED.
Aga Copper Clear (R16+)	_OK=Aga Copper Clear	No arguments. Creates an empty, terminated Copper list owned by the private AGA screen. Returns 1 or 0.
Aga Copper Wait (R18+)	_OK=Aga Copper Wait(v,h)	First argument v: vertical position (0..255). Second argument h: horizontal position (0..222). Consecutive WAIT positions must strictly increase. Returns 1 or 0.
Aga Copper Move (R18+)	_OK=Aga Copper Move(registre,rgb4)	First argument: even colour-register offset $180..$1BE (COLOR00..COLOR31). Second argument: 12-bit RGB4 value $000..$FFF, e.g. $F00 = red. This is not a palette index. Returns 1 or 0.
Aga Copper End (R18+)	_OK=Aga Copper End	No arguments. Seals a nonempty Copper list. Calling End twice, or appending after End, fails. Returns 1 or 0.
Aga Copper On (R17+)	_OK=Aga Copper On	No arguments. Installs the list through Intuition. A nonempty list must have been finalized with End. Returns 1 or 0.
Aga Copper Off (R17+)	_OK=Aga Copper Off	No arguments. Removes the list, restores the display and frees resources owned by the extension. Repeated calls are accepted. Returns 1 or 0.
Aga Mouse X (R19+)	_MX=Aga Mouse X	No arguments. Horizontal position in logical screen pixels (0..width-1), or -1 if outside the screen / closed. Nonblocking.
Aga Mouse Y (R19+)	_MY=Aga Mouse Y	No arguments. Vertical position in logical screen pixels (0..height-1), or -1 if outside the screen / closed. Nonblocking.
Aga Mouse Buttons (R20+, fixed in R21)	_B=Aga Mouse Buttons	No arguments. Integer bitmask 0..7: 1=left, 2=right, 4=middle; bits can be combined (3=left+right), 0=none. Returns -1 if the screen/window or input.device is unavailable. Nonblocking snapshot.
Aga Mouse Pressed (R22+, IDCMP since R23)	_P=Aga Mouse Pressed	No-argument integer function; bitmask 1=left, 2=right, 4=middle, combinable. R23: stores IDCMP_MOUSEBUTTONS press events between reads; 0 if none, -1 for an invalid screen/focus. Each call consumes the pending presses, even after the button was released.
Aga Mouse Released (R22+, IDCMP since R23)	_R=Aga Mouse Released	No-argument integer function; combinable 1/2/4 bitmask. R23: release events remain stored independently of Pressed. Even a complete click between polls can yield both Pressed=1 and Released=1.
Aga Hotspot Hit (M9 R24)	_HIT=Aga Hotspot Hit(_PX,_PY,_X,_Y,_W,_H)	Point-in-rectangle test (6 integer arguments): PX,PY = point to test (e.g. mouse position); X,Y = rectangle top-left corner; W,H = width and height in pixels, NOT right/bottom coordinates. Returns 1 inside, 0 outside, with the right and bottom edges excluded. Does not detect a click or draw/store a hotspot; combine with Aga Mouse Pressed for buttons. Detailed example below.
Aga Rect Overlap (M10 R25)	_C=Aga Rect Overlap(_AX,_AY,_AW,_AH,_BX,_BY,_BW,_BH)	Stateless 8-argument integer function: two rectangles, each with origin (X,Y) and width/height (W,H) in logical pixels. Returns 1 for positive-area overlap (even 1 pixel), 0 for disjoint rectangles, touching edges/corners, or nonpositive dimensions. Negative origins allowed; signed 32-bit overflow is rejected safely. No screen, physics or input state required. R25 WinUAE PASS on the archived scenario.
Aga Text (M11 R26, unchanged in R27)	_OK=Aga Text(_X,_BASELINE_Y,_PEN,_TEXT$)	Four arguments: X pixels, baseline Y, indexed pen, AMOS string (1..128 characters). Draws one line into the AGA Intuition back buffer with temporary RastPort, system font and transparent JAM1. Return 1 if rendered, 0 on invalid state/geometry/string or not-Safe buffer. R26 Gate A+B PASS for text and 40-swap archived scenarios. R27 preserves the entire Text 68000 segment byte-for-byte; its new guards are implemented in Blit Copy/Fill/Clear only. R26 contract · R27 contract.

Copper RGB4 has been available since R18, Mouse X/Y since R19, Mouse Buttons since R20 (with RMBTRAP in R21), and Mouse Pressed/Released since R22. R23 uses IDCMP events to capture button transitions and protect RAWKEY input. The quick-click, keyboard FIFO and Ctrl+C WinUAE scenarios passed; focus-switch and stress scenarios remain untested. Sprites, a Aga Set Colour command, and comprehensive input-stress validation are outside the current scope.

Safe Blitters (M12 R27 — CPU/CI and WinUAE scenario PASS)

The three existing functions Aga Blit Clear, Aga Blit Fill, and Aga Blit Copy now check Safe independently. A return value of 0 can mean Safe has not arrived or another argument/state error; retry only with a bounded VBL wait. A dedicated archived WinUAE test exercises 40 swaps with rotating first operations and no Aga Text probe. The legacy Aga Back Fill instruction is not covered by the R27 protection. Technical contract.

AGA Text (M11 R26 — WinUAE validated on its visual scenario)

With the R26 library installed and the AGA screen/double buffer already open, the function draws on the inactive AGA BitMap, not on a native AMOS screen. Here Y=96 denotes the font baseline; the palette index 28 must already have been defined (e.g. by loading examples/demo.iff):

_TX=Aga Text(40,96,28,"HELLO AGA")
If _TX=1
   _SW=Aga Swap
End If

A result of 0 can mean that the previous front buffer has not yet received its Safe notification. Do not spin indefinitely. This R26 safety check does not automatically secure pre-existing Blitter commands. WinUAE test · technical limits.

Rectangular hotspots (M9 R24)

Aga Hotspot Hit(PX,PY,X,Y,W,H) checks one point against one rectangle, not a collision between two rectangles. It returns an integer assigned to a variable, never a hotspot ID. The first two values are the point coordinates; the remaining four describe the rectangle.

Argument	Meaning	Example
PX, PY	X/Y of the tested point (for instance, Aga Mouse X/Y)	60,50
X, Y	X/Y of the rectangle's top-left corner	40,30
W, H	Width and height, not the opposite corner	80,40
Result (_HIT)	1 = point inside; 0 = outside/invalid	1

For a rectangle (X=40,Y=30,W=80,H=40), the included pixels are X=40..119 and Y=30..69. X=120 or Y=70 is outside (the right and bottom boundaries are excluded). The top and left boundaries are included.

_INSIDE=Aga Hotspot Hit(60,50,40,30,80,40)
_OUTSIDE=Aga Hotspot Hit(120,50,40,30,80,40)
' _INSIDE=1, _OUTSIDE=0

Example: trigger a menu action only when the left mouse button is pressed over this rectangle (run while the AGA screen is open):

_SELECTED=0
_PX=Aga Mouse X
_PY=Aga Mouse Y
_HIT=Aga Hotspot Hit(_PX,_PY,40,30,80,40)
_P=Aga Mouse Pressed
If _P>=0
   _LEFT=_P And 1
   If _LEFT<>0 and _HIT=1
      _SELECTED=10
   End If
End If

Here, 10 is an application-defined button ID, not a value returned by Aga Hotspot Hit. To test several overlapping buttons, call the function for each rectangle and set the ID in the order you want: the last matching assignment wins, as in the validated R24 test.

Limits: negative mouse-point coordinates (including the -1 sentinel from Aga Mouse X/Y) and nonpositive W/H return 0. Negative rectangle X/Y are allowed. The function does not read the mouse, consume input, draw a rectangle or need an open AGA screen. Aga Mouse Pressed is a separate event function; the coordinates read with Aga Mouse X/Y are their current sampled values, not a position saved at the exact click time. See the technical contract.

AGA mouse details (R19–R23)

All five mouse APIs — Aga Mouse X, Aga Mouse Y, Aga Mouse Buttons, Aga Mouse Pressed and Aga Mouse Released — are no-argument integer functions. Use their results in assignments or expressions. Do not write an integer-returning function on a line by itself in AMOS Professional.

_X=Aga Mouse X
_Y=Aga Mouse Y
_B=Aga Mouse Buttons
_P=Aga Mouse Pressed
_R=Aga Mouse Released

If _X>=0 and _Y>=0 and _B>=0
   _LEFT=_B And 1
   _RIGHT=_B And 2
End If

• X/Y coordinates: origin at top left; X ranges from 0 to width-1, Y from 0 to height-1. The return value is -1 for a closed, invalid or out-of-bounds window. Check both coordinates.
• Buttons: 0=none, 1=left, 2=right, 4=middle; combine bits (3=left+right). A -1 result means input is unavailable: verify _B>=0 before applying binary operators.
• Right mouse button (R21): Aga Screen Open enables WFLG_RMBTRAP so the right button does not open Intuition menus over the AGA window. This behaviour was tested under WinUAE.
• Instantaneous state: Aga Mouse Buttons reads a global input.device/PeekQualifier() snapshot. It does not dequeue keyboard messages or track clicks per window; extremely short clicks may be missed.
• R23 edge capture: Aga Mouse Pressed and Aga Mouse Released consume separate pending bitmasks populated from IDCMP_MOUSEBUTTONS by the shared dispatcher. A complete DOWN+UP click received before the poll can set both masks. Reading one does not clear the other. A 16-entry RAWKEY FIFO preserves keyboard input for Aga Key and Aga Wait Key; when full, the dispatcher temporarily stops dequeuing messages. Repeated clicks of the same button within one interval collapse into one bit; these functions are not click counters.

Legacy R21 approach for calculating transitions from consecutive snapshots:

_OLD=Aga Mouse Buttons
_NOW=Aga Mouse Buttons
If _OLD>=0 and _NOW>=0
   _PRESSED=_NOW And (7-_OLD)
   _RELEASED=_OLD And (7-_NOW)
End If

R23 WinUAE tests: the exact archived R23 example using an original 320×256×8 ILBM test card passed with RESULT=1, including PRESSED=RELEASED=3, KEYS=64,64,-1 and WAIT=16 (A on French AZERTY). A separate Ctrl+C test interrupted the program at _WAITK=Aga Wait Key and closed the Intuition screen cleanly (user confirmation). R22's previous test remains archived.

AGA Copper details (R16–R18)

All Aga Copper commands above are integer-returning functions, so assign or use the result. _OK=Aga Copper Off is valid; Aga Copper Off alone is an AMOS syntax error, even in an If branch that is never executed. Return values: 1=success, 0=rejected/failure.

Function	Parameter 1	Parameter 2	Notes
Clear	—	—	Initializes a Copper list owned by the AGA screen. Call it before appending operations.
Wait(v,h)	v: line 0..255	h: position 0..222	Positions must increase; invalid or backward positions return 0.
Move(register,rgb4)	Even register offset $180..$1BE	RGB4 value $000..$FFF	$180=COLOR00, $182=COLOR01 … $1BE=COLOR31. No arbitrary DMA, BPLCON or bitplane-pointer register access.
End	—	—	Seals a nonempty list. Nothing may be appended afterward.
On	—	—	Activates a finalized list; editing while active is rejected.
Off	—	—	Detaches and frees the list; repeated Off calls are accepted.

Move uses 12-bit RGB4, not indexed palette numbers: $F00=red, $0F0=green, $00F=blue, $000=black. For example, Aga Copper Move($180,$F00) changes the value of COLOR00 at the raster point defined by the most recent Wait.

The following sequence is to be run after a successful Aga Screen Open and Aga Double Buffer, optionally with a compatible image loaded. It follows the validated R18 raster example:

_C=Aga Copper Clear
_W1=Aga Copper Wait(20,0)
_M1=Aga Copper Move($180,$F00)
_W2=Aga Copper Wait(80,0)
_M2=Aga Copper Move($180,$0F0)
_W3=Aga Copper Wait(140,0)
_M3=Aga Copper Move($180,$00F)
_W4=Aga Copper Wait(200,0)
_M4=Aga Copper Move($180,$000)
_E=Aga Copper End
_ON=Aga Copper On
_SW=Aga Swap
_K=Aga Wait Key
_OFF=Aga Copper Off

Required order: Clear → Wait/Move pairs → End → On → display/wait → Off → Screen Close. A COLOR00 raster effect is most visible wherever the image uses palette index 0; those pixels may also change colour. The first RGB4 implementation is limited to 62 useful operations plus CEND, with reserved capacity and no free-form AGA register programming.

Validation scope: R16, R17 and R18 passed their specific AMOS interpreted/WinUAE scenarios, including the R18 raster, rejected calls, Off and screen reopening. These tests do not prove AMOS Compiler compatibility, real Amiga hardware behaviour, long-running stability or complete 24-bit AGA palette support. See R18 Copper details and M7 status.

Blitter: Aga Blit Fill, Aga Blit Copy and Aga Blit Clear

These functions require a successful Aga Screen Open followed by Aga Double Buffer. They operate on the back buffer only; call Aga Swap to make the drawing visible.

_OK=Aga Blit Fill(18,24,86,48,15)

Argument	Meaning	Example value
1	x — left coordinate	18
2	y — top coordinate	24
3	width	86 pixels
4	height	48 pixels
5	colourIndex	15 — palette entry index

This rectangle covers x=18..103 and y=24..71 (inclusive): the call does not take x1,y1,x2,y2,colour. The colour index is not RGB. Valid indexed ranges are 0..15 for four bitplanes and 0..255 for eight bitplanes, or more generally 0..(2^depth-1). Special HAM/EHB modes cannot be treated as ordinary indexed RGB palettes.

_OK=Aga Blit Copy(18,24,150,24,86,48)
_OK=Aga Blit Clear(32,40,36,16)

• Copy: source (18,24), destination (150,24), size 86×48. graphics.library/BltBitMap handles overlapping rectangles.
• Clear: sets the 36×16 rectangle at (32,40) to index 0, equivalent to Aga Blit Fill(32,40,36,16,0).
• No clipping: negative coordinates, zero/negative dimensions, out-of-bounds rectangles or an invalid colour index return 0; 1 indicates success.
• Blits are synchronized using WaitBlit. A failure after writing a bitplane does not guarantee that the attempted operation was atomic.
• Aga Back Fill colour fills the entire back buffer, unlike Aga Blit Fill(...).

Typical use

Check the return values from Aga Screen Open and Aga Double Buffer; optionally load an IFF compatible with that screen using Aga Iff Load, perform Blitter operations, then call Aga Swap. For complete runnable AMOS programs with error handling and cleanup, see the validated R13 Copy, R14 Fill and R15 Clear tests.

These M6 scenarios passed under interpreted AMOS/WinUAE. AMOS Compiler and real AGA hardware remain untested for M6.

Reading ILBM image metadata

Aga Pic Info(filename$,field) exposes the following fields:

Field	Return value
0	Width
1	Height
2	Number of bitplanes
3	Number of CMAP palette entries
4	Compression: 0=RAW, 1=ByteRun1
5	Original CAMG value
6	ModeID suitable for opening a screen
7	Number of screen colours to request

The reference image inventory is in docs/ILBM_INVENTORY.md. Before calling Aga Iff Load, you must first open a compatible AGA screen.

Recommended test sequence

M6 R13 Copy, R14 Fill and R15 Clear have passed WinUAE and were moved into tests/passed/. The R12 R12_JEFF_A0_RETRY.asc remains archived. Its historical sequence was:

Aga Pic Info → Aga Screen Open → Aga Double Buffer
→ Aga Iff Load → Aga Swap → Aga Wait Key
→ Aga Screen Close → Amos To Front

AMOS Professional uses If condition / End If (without Then). Close the AGA screen before leaving the program.

Development and integrity

The tools/ directory contains the active builders, dependencies, CPU tests and integrity utilities. Retired tools are kept in tools/obsolete/.

• Current R23 builder: build_m8_idcmp_r23.py, using the immutable R22 archive. The CPU preflight passed 15 scenarios; CPU/CI evidence and live WinUAE validation remain separate.
• Earlier M8 documentation: R20 mouse buttons, R19 mouse X/Y and R21 RMBTRAP.
• Binary integrity: verify_artifacts.py, HUNK/AP20 auditing, SHA-256, reproducibility and GitHub Actions CI.
• API/README parity: test_readme_api_coverage.py checks the command table and active library version in both English and French. Adding an AMOS instruction or function requires documenting it in both language versions within the same change.
• Engineering rules: EXTENSION_SOURCE_RULES.md. State and recovery notes: docs/NEXT_SESSION.md, M8 status, architecture and roadmap.

Current status: M12/R27 0.9.3 Safe Blitters: Gate A native 68000 CPU/CI PASS (403 cases), Gate B interpreted AMOS/WinUAE PASS on the 40-swap visual scenario. The 14,252-byte AP20 library keeps the 31-command token table from R26, changing Blitter code 19/20/21 and required R23 cross-entry/state relocations 6/17/18/31/32/33. The exact original test is archived with no changes; results: DONE 40 C 14 F 13 P 13, C0 13 F0 13 P0 13 SWAP0 0, zero final errors, CLOSED -1 RESULT 1, normal exit at AMOS line 167. The user observed blinking rectangles. No active test remains. R26/R25/R24 and LAST_GOOD R10 frozen. No FPS benchmark, exhaustive stress, Compiler or hardware AGA pass. M12 report.