MTXLib - A library of SDCC callable subroutines for the MTX

The Routines

The routines in MTXLib are currently mostly direct equivalents to MTX BASIC commands. See the Memotech documentation for further details. The routines are generally direct entries into MTX ROM routines, with no error checking. Incorrect parameter values will, at best, result in one of the usual MTX BASIC cryptic error codes, or may result in a crash requiring a reboot.

unsigned char inport (unsigned int addr);

Read a value from a Z80 I/O port. The full 16 bit address is used. The only known MTX add-on which makes use of the high byte of the address is Speculator.

Include file: ioport.h

void outport (unsigned int addr, unsigned int data);

Write a to from a Z80 I/O port. The full 16 bit address is used. The only known MTX add-on which makes use of the high byte of the address is Speculator. The data is specified as 16-bit as this results in a more efficient subroutine call. Only the lower byte of the data variable is actually used.

Include file: ioport.h

int putchar (int c);

Displays a character.

Include file: stdio.h

int getchar (void);

Reads a character from the keyboard. Waits until the key has been released.

Include file: stdio.h

void adjspr (unsigned char p, unsigned char n, unsigned char v);

Adjusts a value asigned to a sprite.

p = Parameter to assign (see table below).
n = Sprite number.
v - Value to assign.

pMeaningRange for v
0Pattern0 - 127 for size 0 sprites
0 - 31 for size 1 sprites
1Colour0 - 15
2X position0 - 255
3Y position0 - 255
4X speed0 - 255 (128 - 255 treated as negative)
5Y speed0 - 255 (128 - 255 treated as negative)

Include file: mtxscrn.h

void attr (unsigned char p, unsigned char state);

Sets plotting attributes on a graphics screen.

p = 0 - Inverse print.
p = 1 - Over print.
p = 2 - Unplot.
p = 3 - Over-plot.
state = 0 - Off.
state = 1 - On.

>

Include file: mtxscrn.h

void cls (void);

Clears the screen.

Include file: mtxscrn.h

void colour (unsigned char p, unsigned char n);

Sets the colour for the graphics screen.

p = 0 - Print paper.
p = 1 - Print ink.
p = 2 - Non-print paper.
p = 3 - Non-print ink.
p = 4 - Border colour.
n = Colour (0-15).

Include file: mtxscrn.h

void crvs (unsigned char n, unsigned char t, unsigned char x, unsigned char y, unsigned char w, unsigned char h, unsigned char s);

Create and select a virtual screen.

n = Virtual screen number (0 - 7).
t = Type of screen (0 = text, 1 = graphics).
x = Horizontal position of left corner (0 - 39 or 31).
y = Vertical position of top corner (0 - 23).
w = Width of virtual screen (x + w <= 40 or 32).
h = Height of virtual screen (y + h <= 24).
s = Physical screen width (40 or 32).

Include file: mtxscrn.h

void csrdown (void);

Move the cursor down one line.

Include file: mtxscrn.h

void csrhome (void);

Move the cursor to top left.

Include file: mtxscrn.h

void csrleft (void);

Move the cursor left one character.

Include file: mtxscrn.h

void csroff (void);

Turn off the flashing cursor.

Include file: mtxscrn.h

void csron (void);

Turn on the flashing cursor.

Include file: mtxscrn.h

void csrright (void);

Move the cursor right one character.

Include file: mtxscrn.h

void csrup (void);

Move the cursor up one line.

Include file: mtxscrn.h

void ctlspr (unsigned char p, unsigned char v);

Set parameters to control sprites:

pMeaningRange for v
0Speed (1 is fastest)1 - 255, 0 = 256
1Distance to move1 - 255
2Number of sprites0 - 32
3Number of circling sprites0 - 32
4Plot sprite number0 - 32
5Number of moving sprites0 - 32
6Magnitude and size0 = 8x8 mag 1
1 = 8x8 mag 2
2 = 16x16 mag 1
3 = 16x16 mag 2

Include file: mtxscrn.h

void cursor (unsigned char x, unsigned char y);

Sets the cursor position.

x = Horizontal position (0 - 31 or 39).
y = Vertical position (0 - 23).

Include file: mtxscrn.h

void eol (void);

Erase to end of line.

Include file: mtxscrn.h

void genpat (unsigned char p, unsigned char n, unsigned char d1, unsigned char d2, unsigned char d3, unsigned char d4, unsigned char d5, unsigned char d6, unsigned char d7, unsigned char d8);

Define a pattern for a character or sprite.

p>Meaningnd1 ... d8
0Redefine an ASCII character32 - 127Pixels for each row
1Redefine a non-ASCII character129 - 154Pixels for each row
2Colours for each row of a character147 - 15416 * paper + ink
3Pattern for 8x8 sprite0 - 127Pixels for each row
4NW quarter of a 16x16 sprite0 - 31Pixels for each row
5SW quarter of a 16x16 sprite0 - 31Pixels for each row
6NE quarter of a 16x16 sprite0 - 31Pixels for each row
7SE quarter of a 16x16 sprite0 - 31Pixels for each row

Include file: mtxscrn.h

void ink (unsigned char clr);

Set the ink colour (0 - 15).

Include file: mtxscrn.h

char inkey (void);

Test for a key pressed. Returns the character code, or zero if no key pressed.

Include file: mtxscrn.h

void line (unsigned char x1, unsigned char y1, unsigned char x2, unsigned char y2);

Plot a line from (x1, y1) to (x2, y2).

Include file: mtxscrn.h

void movspr (unsigned char p, unsigned char n, unsigned char d);

Controls a sprite in a number of ways. The value of p can be summed to perform multiple actions. The value of d must be consistent with all the selected actions.

n = Sprite number (1 - 32).

pMeaningd
1Move sprite 1 stepDirection of movement (0 - 8)
2Change the sprites patternPattern number (0 - 31 or 127)
4Change the direction of sprite movementDirection of movement (0 - 8)
8Plot at centre of spriteIgnored

Include file: mtxscrn.h

void pagemode (void);

Selects page mode for the screen.

Include file: mtxscrn.h

void paper (unsigned char clr);

Selects the paper colour (0 - 15).

Include file: mtxscrn.h

void plot (unsigned char x, unsigned char y);

Plots a point at (x, y).

Include file: mtxscrn.h

void scrlmode (void);

Selects scroll mode for the screen.

void sprite (unsigned char n, unsigned char p, unsigned int xp, unsigned int yp, signed char xs, signed char ys, unsigned char c);

Defines a sprite:

n = Sprite number (1 - 32).
p = Pattern number (0 - 127 for 8x8 sprites, 0 - 31 for 16x16 sprites).
xp = Horizontal position of sprite centre (0 - 4059).
yp = Vertical position of sprite centre (0 - 4059).
xs = Horizontal speed (-128 - 127).
ys = Vertical speed (-128 - 127).
c = Colour (0 - 15).

Include file: mtxscrn.h

void view (unsigned char dir, unsigned char dis);

Move the graphics screen relative to the sprite planes.

dir = Direction (0 - 7).
dis = Distance (0 - 255).

Include file: mtxscrn.h

void vs (unsigned char n);

Select a virtual screen.

n = Virtual screen number (0 - 7).

Include file: mtxscrn.h

void killsnd (void);

Turn off all sound.

Include file: mtxsnd.h

void pause (unsigned int wait);

Pause for a period. The duration of the pause is determined by the number of interrupts occurring. By default, in BASIC, that is one every 8ms.

wait = Number of interrupt periods to wait for.

Include file: mtxsnd.h

void sbuf (unsigned int nbuf);

Define the number of sound buffers to use for each channel.

Include file: mtxsnd.h

void sound3 (unsigned int chan, unsigned int freq, unsigned int vol);

Starts a sound. The sound will continue untill changed by another command.

chan = Sound channel (0 - 3).
freq = Frequency (0 - 1023).
vol = Volume (0 - 15).

Include file: mtxsnd.h

void sound7 (unsigned int chan, unsigned int freq, unsigned int vol, unsigned int finc, unsigned int vinc, unsigned int durn, unsigned int mode);

Define a sound transition. The duration is specified in multiples of 16ms, and the frequency and volume increments are applied every 16ms.

chan = Sound channel (0 - 3).
freq = Frequency (0 - 8191).
vol = Volume (0 - 1023).
finc = Frequency increment.
vinc = Volume increment.
durn = Duration of transition.
mode = 0 - Continue from previous frequency and volume (ignore new values).
mode = 1 - Start at specified new frequency and volume.

Include file: mtxsnd.h