Add a compile script and instructions

COMPILE.md

@@ -0,0 +1,10 @@
+# AgDev - compile instructions
+
+A script ```compile.sh``` can be used to compile this source tree.
+It is a Linux only compile script. 
+
+You should clone the repo or extract the release, then just run the bash script `compile.sh`
+As part of the script it will download https://github.com/CE-Programming/toolchain/releases/latest/download/CEdev-Linux.tar.gz
+
+After the code is compiled, move the CEdev directory to wherever you desire and add the CEdev/bin directory to your path.
+

README.md

@@ -1224,206 +1224,16 @@ Both of  which output directly to MOS/VDP - note that they are not part of STDIO
 
 ### VDU Commands
 
-From [VDP - breakintoprogram/agon-docs GitHub Wiki](https://github-wiki-see.page/m/breakintoprogram/agon-docs/wiki/VDP), with any clarifications from testing or examining the VDP source code. 
+For current documentation on VDU commands, see the [Agon Console8 Documentation](https://agonconsole8.github.io/agon-docs/VDP.html)
 
-- `VDU 32-126`: normal ASCII text output
+These can be called by sending the appropriate control characters using `putch()` or `mos_puts()` as mentioned.
 
-- `VDU 4`: seems to be setGlyphOptions for text
+Convenience functions for many of these are supplied in AgDev.
 
-- `VDU 5`: seems to be setGlyphOptions for graphics
+For example, to change the screen MODE to 3, the C call `vdp_mode(3);` will send `22,3` as single bytes to the output, equivalent to `putch(22);putch(3);`
 
-- `VDU 7`: bell - plays a note
+For a list of the commands see `include/agon/vdp_vdu.h`
 
-- `VDU 8`: cursor left
-
-- `VDU 9`: cursor right
-
-- `VDU 10`: cursor down (line-feed)
-
-- `VDU 11`: cursor up
-
-- `VDU 12`: clear screen
-
-- `VDU 13`: carriage return
-
-- `VDU 14`: page mode on
-
-- `VDU 15`: page mode off
-
-- `VDU 16`: CLG (clear graphics - presumably)
-
-- `VDU 17, colour`: set the text foreground colour
-
-- `VDU 18, mode, colour`: GCOL (graphics colour - presumably)
-
-- `VDU 19, l, p, r, g, b`: define logical palette - colour l, p / colour l, r, g, b
-
-- `VDU 22, n`: mode n
-
-- `VDU 23, n`: UDG / system commands
-
-- `VDU 24, left; bottom; right; top;`: define a graphics viewport (VDP 1.04 or later)
-
-- `VDU 25, mode, x; y;`: PLOT mode, x, y
-
-- `VDU 26`: reset text and graphics viewports (VDP 1.04 or later)
-
-- `VDU 28, left, bottom, right, top`: define a text viewport (VDP 1.04 or later)
-
-- `VDU 29, x; y;`: set graphics origin
-
-- `VDU 30`: cursor home (move cursor to top left of viewport)
-
-- `VDU 31, x, y`: tab(X, Y)
-
-- `VDU 127`: backspace
-
-Values followed by `;` are two byte words (little endian), otherwise value are single bytes.
-
-#### VDU 23 Commands
-
-##### VDU 23,0: VPD Commands
-
-VDU 23, 0 is reserved for commands sent to the VDP
-
-- `VDU 23, 0, &81, n`: Set the keyboard locale (0=UK, 1=US, etc)
-- `VDU 23, 0, &82`: Request cursor position
-- `VDU 23, 0, &83, x; y;`: Get ASCII code of character at character position x, y
-- `VDU 23, 0, &84, x; y;`: Get colour of pixel at pixel position x, y
-- `VDU 23, 0, &85, channel, waveform, volume, freq; duration;`: Send a note to the VDP audio driver
-- `VDU 23, 0, &86`: Fetch the screen dimensions
-- `VDU 23, 0, &87`: RTC control (Requires MOS 1.03 or above)
-  - `VDU 23, 0, &87, 0`: Read the RTC
-  - `VDU 23, 0, &87, 1, y, m, d, h, m, s`: Set the RTC
-- `VDU 23, 0, &88, delay; rate; led`: Keyboard Control (Requires MOS 1.03 or above)
-- `VDU 23, 0, &C0, n`: Turn logical screen scaling on and off, where 1=on and 0=off (Requires MOS 1.03 or above)
-- `VDU 23, 0, &FF`: Switch to terminal mode for CP/M (This will disable keyboard entry in BBC BASIC/MOS)
-
-Commands between &82 and &88 will return their data back to the eZ80 via the serial protocol
-
-##### VDU 23, 1: Cursor display
-
-- `VDU 23, 1, 0`: Disable the text cursor
-- `VDU 23, 1, 1`: Enable the text cursor
-
-##### VDU 23, 7: Scrolling
-
-- `VDU 23, 7, extent, direction, speed`: Scroll a rectangle on the screen
-  - Extent (0 = text viewport, 1 = entire screen, 2 = graphics viewport)
-  - Direction (0 = right, 1 = left, 2 = down, 3 = up)
-  - Speed: number of pixels to scroll
-
-##### VDU 23, 16: Define Cursor Behaviour (Requires VDP 1.04 or greater)
-
-- `VDU 23, 16, setting, mask`: Specify by ANDing with mask then XORing with setting
-
-The following bits are implemented in VDU 23, 16
-
-- `Bit 0 = 1`: Enable scroll protection - text cursor will not scroll when it moves off the bottom/right of the viewport
-- `Bit 0 = 0`: Disable scroll protection (default)
-- `Bit 4 = 1`: Text cursor will wrap to top of screen when it moves off the bottom of the screen
-- `Bit 4 = 0`: Text cursor will scroll when it moves off the bottom of the screen (default)
-- `Bit 5 = 1`: Cursor does not move right after a character is printed
-- `Bit 5 = 0`: Cursor moves right after a character is printed (default)
-- `Bit 6 = 1`: Graphics cursor (VDU 5 mode) carries on off edge of graphics viewport
-- `Bit 6 = 0`: Graphics cursor does an implicit cr/lf when it moves off right of graphics viewport (default)
-
-##### VDU 23, 27: Sprites and Bitmaps
-
-VDU 23, 27 is reserved for the bitmap and sprite functionality
-
-Note that there are differences between the way the emulator and Agon Light hardware handles bitmaps.
-
-- Emulator does not have a memory limit, which means it is possible to load large bitmaps
-
-  - On the real hardware if a large bitmap is loaded this starts to reduce the amount of memory for the display. For example in mode 3, if a 180x50 bitmap is loaded, the vertical height of mode 3 is reduced from 480 to 356 pixels.
-
-- In mode 0 which is 2 colour, emulator still shows multi-colour images, whereas on the actual HW they are black and white
-
-**Bitmaps**
-
-- `VDU 23, 27, 0, n`: Select bitmap n
-
-- `VDU 23, 27, 1, w; h; r1, g1, b1, a1, r2, g2, b2, a2, ...`: Load colour bitmap data into current bitmap
-
-  - Data is in RGBA format - i.e. 32 bits per pixel
-
-- `VDU 23, 27, 2, w; h; r, g, b, a`: Load solid bitmap data into current bitmap
-
-  - Note that this is from checking the code, the documentation incorrectly says:
-  - ```
-    `VDU 23, 27, 2, w; h; col1; col2; b1, b2 ... bn: Load monochrome bitmap data into current bitmap`
-    ```
-
-- `VDU 23, 27, 3, x; y;`: Draw current bitmap on screen at pixel position x, y
-
-Up to 255 bitmaps are supported
-
-Images (.png) can be converted to the correct format using imagemagick:
-
-```
-convert source.png dest.rgba
-```
-
- **Sprites**
-
-- `VDU 23, 27, 4, n`: Select sprite n
-- `VDU 23, 27, 5`: Clear frames in current sprite
-- `VDU 23, 27, 6, n`: Add bitmap n as a frame to current sprite
-- `VDU 23, 27, 7, n`: Activate n sprites
-- `VDU 23, 27, 8`: Select next frame of current sprite
-- `VDU 23, 27, 9`: Select previous frame of current sprite
-- `VDU 23, 27, 10, n`: Select the nth frame of current sprite
-- `VDU 23, 27, 11`: Show current sprite
-- `VDU 23, 27, 12`: Hide current sprite
-- `VDU 23, 27, 13, x; y;`: Move current sprite to pixel position x, y
-- `VDU 23, 27, 14, x; y;`: Move current sprite by x, y pixels
-- `VDU 23, 27, 15`: Update / refresh the sprites in the GPU
-- `VDU 23, 27, 16`: Reset the sprites and clear all data (Requires MOS 1.03 or above)
-
-Sprites reference underlying bit maps
-
-Sprite creation order:
-
-1) Create bitmap(s) for sprite, or re-use bitmaps already created
-
-2) Select the correct sprite ID (0-255). The GDU only accepts sequential sprite sets, starting from ID 0. All sprites must be adjacent to 0
-
-3) Clear out any frames from previous program definitions
-
-4) Add one or more frames to each sprite
-
-5) Activate sprite to the GDU
-
-6) Show sprites on screen / move them around as needed
-
-7) Refresh
-
-##### VDU 23, ASCII-code: User Defined Characters (UDG)
-
-- `VDU 23, ascii-code, n1, n2, n3, n4, n5, n6, n7, n8`: redefine character with ASCII code (>=32).
-
-#### VDU 25 Plot Commands
-
-- `VDU 25, &04, x; y;`: move to
-
-- `VDU 25, &05, x; y;`: line to
-
-- `VDU 25, &40-&47, x; y;`: point
-
-  - &40-&47: makes no difference which value is used
-
-- `VDU 25, &50-&57, x; y;`: triangle (filled)
-
-  - &50-&57: makes no difference which value is used
-
-- `VDU 25, &90-&97, x; y;`: circle (not filled)
-
-  - &90-93: circle centred on current point, with radius specified by either x or y
-
-  - &94-97: circle centred on current point passing through x, y
-
-Three successive points are maintained, updated whenever a call is made to VDU25. These are used, for example, for the vertices of the triangle.
 
 ## VDP / Keyboard Interrupts
 

compile.sh

@@ -0,0 +1,100 @@
+#!/bin/bash -x
+
+# Working directory
+BASEDIR=`pwd`/build
+
+GITHUB=$BASEDIR/github
+if [ ! -d "$BASEDIR" ]
+then
+       	mkdir $BASEDIR
+fi
+if [ ! -d "$GITHUB" ]
+then
+       	mkdir $GITHUB
+fi
+
+# tar file of the CE Toolchain
+# Available from here https://github.com/CE-Programming/toolchain/releases/latest/download/CEdev-Linux.tar.gz
+cd $BASEDIR
+wget https://github.com/CE-Programming/toolchain/releases/latest/download/CEdev-Linux.tar.gz
+CEDEV_TAR=$BASEDIR/CEdev-Linux.tar.gz
+
+# this is where you checkout the Source Code of CEdev
+# and you will compile it with the AgDev mods and your own
+# customisations.
+# See agdev_make.sh for a script to do this build
+CEDEV_GIT=$GITHUB/CEdev
+
+# this is where you want your working CEdev directory
+# to be - this is where you will build and compile code
+CEDEV_FINAL=$BASEDIR/CEdev
+
+
+# before you start you must have the modified CEdev
+# extracted and CEdev/bin in your path
+# this is so it can find the ez80-clang compiler
+cd $BASEDIR; tar xf $CEDEV_TAR ; PATH=$PATH:$BASEDIR/CEdev/bin
+
+#----------------------------------------
+# get latest AgDev code
+# Only do this if you want AgDev updates
+#----------------------------------------
+cd $GITHUB
+rm -rf $GITHUB/AgDev
+git clone https://github.com/pcawte/AgDev.git
+
+AGDEV_GIT=$BASEDIR/github/AgDev
+
+#----------------------------------------
+# get latest CEdev code
+# Only do this if you want toolchain updates
+#----------------------------------------
+cd $GITHUB
+rm -rf $GITHUB/CEdev
+git clone https://github.com/CE-Programming/toolchain.git CEdev
+cd CEdev
+git submodule update --init --recursive
+
+CEDEV_GIT=$GITHUB/CEdev
+
+#----------------------------------------
+# Copy in AgDev code to CEdev toolchain code
+#----------------------------------------
+cp -r $AGDEV_GIT/src/* $CEDEV_GIT/src/
+cp -r $AGDEV_GIT/include/* $CEDEV_GIT/src/include
+
+# Remove the previous build directory and make
+cd $CEDEV_GIT
+rm -rf CEdev
+#make clean
+make install
+
+# will result in a install directory $CEDEV_GIT/CEdev/CEdev
+# because of the strange way the AgDev common.mk file sets up the
+# install directories
+
+#----------------------------------------
+# Install
+#----------------------------------------
+
+# delete previous CEdev final directory
+rm -rf $CEDEV_FINAL
+
+# Get the full version of CEdev from the TAR file
+cd /tmp ; rm -rf CEdev
+tar xf $CEDEV_TAR
+mv CEdev $CEDEV_FINAL
+
+# ... but now we can get our modified version which was created with agdev_make.sh
+cp -rf $CEDEV_GIT/CEdev/CEdev $CEDEV_FINAL
+
+# Copy over the AgDev stuff - this includes the ez80_clang compiler
+# and example code
+cp -rf $AGDEV_GIT/* $CEDEV_FINAL/
+
+# now copy over the built binaries and libraries
+cp $CEDEV_GIT/CEdev/CEdev/bin/* $CEDEV_FINAL/bin/
+cp -r $CEDEV_GIT/CEdev/CEdev/lib/libc/vdp* $CEDEV_FINAL/lib/agon/
+# finally copy the modified headers to the include directory
+cp $CEDEV_FINAL/src/libc/include/vdp*h $CEDEV_FINAL/include/agon/
+