Skip to content

agonplatform.md

Latest commit

 

History

History
209 lines (154 loc) · 8.05 KB

agonplatform.md

File metadata and controls

209 lines (154 loc) · 8.05 KB
Raw

Agon specific implementation details

LOAD/SAVE

The following file extensions are supported:

  • .BBC: LOAD and SAVE in BBC BASIC (Z80) tokenised format
  • .BAS: LOAD and SAVE in plain text format (also .TXT and .ASC)

If a file extension is omitted, ".BBC" is assumed.

Line editing

Lines can be edited by using:

  1. *EDIT <linenumber>
  2. *<linenumber> - starting at the given linenumber, the user is allowed to scroll through the listing using arrow-keys and/or j/k keys to select a line to edit. Press RETURN, left arrow or BACKSPACE to confirm selection of the line to edit. Escape to quit.

STAR (*) commands

The following commands are supported in this port:

*ASM

Run the assembler

*BYE

Exit BBC BASIC and return to MOS - equivalent to QUIT

*EDIT / *<linenum>

Syntax: *EDIT linenum Syntax: *<linenum>

Pull a line into the MOS line editor for editing

*FX

Syntax: *FX osbyte, params Execute an OSBYTE command.

The OSBYTE commands supported at the moment are:

  • 19: Wait for vertical blank retrace
  • 11: Set keyboard repeat delay in ms (250, 500, 750 or 1000) - MOS 1.03+
  • 12: Set keyboard repeat rate ins ms (between 33 and 500ms) - MOS 1.03+
  • 118: Set keyboard LED (Bit 0: Scroll Lock, Bit 1: Caps Lock, Bit 2: Num Lock) - does not currently change status, just the LED - MOS 1.03+

*VERSION

Display the current Agon release version of BBC BASIC

AGON MOS integration

For the most part, the MOS is transparent to BASIC; most of the operations via the MOS and VDP are accessed via normal BBC BASIC statements, with the following exceptions:

Accessing the MOS SysVars

MOS has a small area of memory for system state variables (sysvars) which lives in an area of RAM outside of the area in which BBC BASIC runs. To access these, you will need to do an OSBYTE call

Example: Print the least significant byte of the internal clock counter

10 L%=&00 : REM The sysvar to fetch
20 A%=&A0 : REM The OSBYTE number
30 PRINT USR(&FFF4)

Documentation for the full list of sysvars can be found in the MOS API documentation

Running star commands with variables

The star command parser does not use the same evaluator as BBC BASIC, so whilst commands can be run in BASIC, variable names are treated as literals.

Example: This will NOT work

10 INPUT "Filename";f$
20 INPUT "Load Address";addr%
30 *LOAD f$ addr%

To do this correctly, you must call the star command indirectly using the OSCLI command Example: This will work

30 OSCLI("LOAD " + f$ + " " + STR$(addr%))

Inline assembler

The inline ez80 assembler defaults to ADL 1 mode, as this best fits the default ADL mode of the BBC Basic port. The ADL assembler directive can be used to change this behavior.

ADVAL channels

ADVAL(0) returns the fire buttons as per the BBC Micro User guide in a 16-bit number, plus some extras: Bits:

  • 0 - joystick1 fire button pressed
  • 1 - joystick2 fire button pressed
  • 2 - joystick1 2nd fire button pressed
  • 3 - joystick2 2nd fire button pressed
  • 8 - always 1, to indicate virtual BBC Micro ADC channel '1' has completed the ADC conversion.

Examples:

  • X=0 no button pressed

  • X=1 joystick1 fire button pressed

  • X=2 joystick2 fire button pressed

  • X=3 both fire buttons pressed

  • ADVAL(1) - Returns joystick1 X channel as virtual ADC value (0 = left, 32768 center, 65520 right)

  • ADVAL(2) - Returns joystick1 Y channel as virtual ADC value (0 = down, 32768 center, 65520 up)

  • ADVAL(3) - Returns joystick2 X channel as virtual ADC value

  • ADVAL(4) - Returns joystick2 Y channel as virtual ADC value

ADVAL(5) - Returns all digital joystick pins as a single 16bit number (1 = on, 0 = off)

  • 15 - joystick1 2nd fire button
  • 14 - joystick2 2nd fire button
  • 13 - joystick1 fire button
  • 12 - joystick2 fire button
  • 11 - not used
  • 10 - not used
  • 09 - not used
  • 08 - not used
  • 07 - joystick1 right
  • 06 - joystick2 right
  • 05 - joystick1 left
  • 04 - joystick2 left
  • 03 - joystick1 down
  • 02 - joystick2 down
  • 01 - joystick1 up
  • 00 - joystick2 up

Other ADVAL channel values are ignored and return 0

ENVELOPE

The BBC Basic ENVELOPE keyword will not be implemented on the Agon platform. Agon's VDP has a rich audio API with different envelope options per channel, that can be easily accessed/set through the VDU keyword. Please see the AgonPlatform VDP Enhanced audio API

INKEY behavior

Syntax: <n-var>=INKEY(<numeric>) INKEY behaves as documented for 0 or positive numeric clock ticks, as a wait time limit. The function does a GET, waiting for a maximum of 'num' clock ticks of 10ms each. If no key is pressed in the time limit, INKEY will return -1. The INKEY function will return the ASCII value of the key pressed.

A negative parameter can be specified as a RISCOS-compatible keyvalue to immediately check for. INKEY returns with -1 when the given key is pressed, or 0 if not pressed.

TINT behavior

Syntax: <n-var>=TINT(X,Y)

TINT can be used to get the current 32bit colorvalue of a single pixel in BGR format. Each B/G/R color is 8bit. The upper 8bit of the 32bit colorvalue is set to 0 always. Setting a colorvalue isn't implemented.

MODE

The modes differ from those on the BBC series of microcomputers. The full list can be found here in the VDP documentation.

COLOUR

Syntax: COLOUR c Change the the current text output colour

  • If c is between 0 and 63, the foreground text colour will be set
  • If c is between 128 and 191, the background text colour will be set

Syntax: COLOUR l,p

Set the logical colour l to the physical colour p

Syntax: COLOUR l,r,g,b

GCOL

Syntax: GCOL mode,c Set the graphics colour c, and the "mode" of graphics paint operations.

Colour values are interpreted as per the COLOUR command, i.e. values below 128 will set the foreground colour, and values above 128 set the background colour.

Versions of the VDP earlier than 1.04 only supported mode 0, with all painting operations just setting on-screen pixels.

VDP 1.04 introduced partial support for mode 4, which inverts the pixel. Mode 4 would only apply to straight line drawing operations. The mode would affect all applicable plot operations.

As of Console8 VDP 2.6.0, all 8 of the basic modes are supported for all currently supported plot operations. Separate plot modes are now tracked for foreground and background colours, and the mode is applied to the graphics operation. GCOL paint modes

POINT

Syntax: <n-var>=POINT(X,Y) This returns the physical colour index of the colour at pixel position (x, y)

PLOT

Syntax: PLOT mode,x,y For information on the various PLOT modes, please see the VDP PLOT command documentation

GET

Syntax: <n-var>=GET(X,Y) returns the ASCII code of the character at position x, y

Syntax: <n-var>=GET(p) Read and return the value of eZ80 port p

GET$

Syntax: <str-var>=GET$(X,Y) Returns the ASCII character at position x,y as a string

SOUND

Syntax: SOUND channel,volume,pitch,duration Play a sound through the Agon Light buzzer and audio output jack

  • Channel: 0 to 2
  • Volume: 0 (off) to -15 or 15 (full volume)
  • Pitch: 0 to 255
  • Duration: -1 to 254 (duration in 20ths of a second, -1 = play forever)

TIME$

Access the ESP32 RTC data

Example:

  10 REM CLOCK
  20 :
  30 CLS
  40 PRINT TAB(2,2); TIME$
  50 GOTO 40

NB: This is a virtual string variable; at the moment only getting the time works. Setting is not implemented.

VDU

The VDU commands on the Agon Light will be familiar to those who have coded on Acorn machines. Please read the VDP documentation for details on what VDU commands are supported.