This wiki is being migrated to http://www.github.com/z88dk/z88dk/wiki

User Tools

Site Tools


library:zxspectrum

Table of Contents

ZX Spectrum LIBRARY (spectrum.h)

Header {z88dk}/include/spectrum.h
Source {z88dk}/libsrc/spectrum
Include #include <spectrum.h>
Linking n/a
Compile n/a
Supported ZX Spectrum, TS 2068 (partially)
Comments n/a

The ZX Spectrum library contains functions specific to the Sinclair Spectrum family machines.

Constants

Attributes

INK_BLACK0x00
INK_BLUE0x01
INK_RED0x02
INK_MAGENTA0x03
INK_GREEN0x04
INK_CYAN0x05
INK_YELLOW0x06
INK_WHITE0x07
PAPER_BLACK0x00
PAPER_BLUE0x08
PAPER_RED0x10
PAPER_MAGENTA0x18
PAPER_GREEN0x20
PAPER_CYAN0x28
PAPER_YELLOW0x30
PAPER_WHITE0x38
BRIGHT0x40
FLASH0x80

BASIC language keyword tokens

These are the defined constants for the BASIC KEYWORDS

RNDTK_RND165
INKEY$TK_INKEYS166
PITK_PI167
FNTK_FN168
POINTTK_POINT169
SCREEN$TK_SCREENS170
ATTRTK_ATTR171
ATTK_AT172
TABTK_TAB173
VAL$TK_VALS174
CODETK_CODE175
VALTK_VAL176
LENTK_LEN177
SINTK_SIN178
COSTK_COS179
TANTK_TAN180
ASNTK_ASN181
ACSTK_ACS182
ATNTK_ATN183
LNTK_LN184
EXPTK_EXP185
INTTK_INT186
SQRTK_SQR187
SGNTK_SGN188
ABSTK_ABS189
PEEKTK_PEEK190
INTK_IN191
USRTK_USR192
STR$TK_STRS193
CHR$TK_CHRS194
NOTTK_NOT195
BINTK_BIN196
ORTK_OR197
ANDTK_AND198
< = TK_LEQ199
> = TK_GEQ200
< > TK_NEQ201
LINETK_LINE202
THENTK_THEN203
TOTK_TO204
STEPTK_STEP205
DEF FNTK_DEF_FN206
CATTK_CAT207
FORMATTK_FORMAT208
MOVETK_MOVE209
ERASETK_ERASE210
OPENTK_OPEN211
CLOSETK_CLOSE212
MERGETK_MERGE213
VERIFYTK_VERIFY214
BEEPTK_BEEP215
CIRCLETK_CIRCLE216
INKTK_INK217
PAPERTK_PAPER218
FLASHTK_FLASH219
BRIGHTTK_BRIGHT220
INVERSETK_INVERSE221
OVERTK_OVER222
OUTTK_OUT223
LPRINTTK_LPRINT224
LLISTTK_LLIST225
STOPTK_STOP226
READTK_READ227
DATATK_DATA228
RESTORETK_RESTORE229
NEWTK_NEW230
BORDERTK_BORDER231
CONTINUETK_CONTINUE232
CONTTK_CONT232
DIMTK_DIM233
REMTK_REM234
FORTK_FOR235
GO TOTK_GO_TO236
GO SUBTK_GO_SUB237
INPUTTK_INPUT238
LOADTK_LOAD239
LISTTK_LIST240
LETTK_LET241
PAUSETK_PAUSE242
NEXTTK_NEXT243
POKETK_POKE244
PRINTTK_PRINT245
PLOTTK_PLOT246
RUNTK_RUN247
SAVETK_SAVE248
RANDOMIZETK_RANDOMIZE249
RANDOMIZETK_RAND249
IFTK_IF250
CLSTK_CLS251
DRAWTK_DRAW252
CLEARTK_CLEAR253
RETURNTK_RETURN254
COPYTK_COPY255

Configuration diagnostics

Since there are many different hardware configurations, having some sort of diagnosis can greatly help the developer to build compatible software.

Unluckily some of those routines won't work on the standard 2A, 3 or Pentagon models. The zx_model function can help in those cases.

int zx_128mode()

TRUE if in Spectrum 128 mode

int zx_issue3()

TRUE if your spectrum model is issue 3 or more. Works by checking the keyboard behaviour.

int zx_type()

Identifies your Spectrum type

048K
1128K
2TS2068

int zx_model()

Identifies your Spectrum model:

0unknown
148K
2128K or +2
3 +2A or Pentagon
4 +3
5 +2A/ +3 with bus fixed for games
6TS2068

int zx_basic_length()

Computes the size of the BASIC program in memory (if any).

int zx_var_length()

Computes the current size of the BASIC variables area.

int zx_printer()

Returns TRUE if the ZX Printer is attached.

int zx_soundchip()

Returns TRUE if some sort of Yamaha soundchip is connected as for the Spectrum 128.

int zx_timexsound()

zx_fullerstick()

int zx_kempstonmouse()

int zx_kempston()

Returns TRUE if a Kempston Joystick interface is connected.

int zx_iss_stick()

Returns TRUE if an ISS Joystick interface is connected.

int zx_multiface()

int zx_disciple()

Returns TRUE if a Disciple / D interface is connected

int zx_plus3fdc()

Returns TRUE if the Spectrum 3 floppy disk controller is present.

int zx_trd()

Returns TRUE if TRDOS is active.

int zx_extsys()

Returns TRUE if if some sort of system extension has moved the BASIC program.

int zx_basemem()

Gives the size of the base memory (normally 16K or 48K).

Interfacing to the ZX Spectrum BASIC

int zx_goto(int line)

Runs a BASIC portion, starting at the given line. The returned value is zero or the BASIC error code, if any.

int zx_getstr(char variable, char *value)

Load the specified BASIC string variable into *value.

void zx_setstr(char variable, char *value)

Copies the string pointed by *value in the specified BASIC string variable, creating it if necessary.

int zx_getint(char *variable)

Return the integer value for the specified BASIC numeric variable.

void zx_setint(char *variable, int value)

Copies “value” to the specified BASIC variable. *variable should be set with the BASIC variable name.

double zx_getfloat(char *variable)

Return the floating point value for the specified BASIC numeric variable.

void zx_setfloat(char *variable, float value)

Copies “value” (double type format) to the specified BASIC variable, creating it if necessary. *variable must be set with the BASIC variable name.

Tape I/O

Standard tape header structure

  struct zxtapehdr {
           unsigned char type;
           char    name[10];
           size_t length;
           size_t address;
           size_t offset;
  };

int tape_save(char *name, size_t loadstart,void *start, size_t len)

int tape_save_block(void *addr, size_t len, unsigned char type)

int tape_load_block(void *addr, size_t len, unsigned char type)

Input Devices: Keyboard, Joystick and Mice

Reading input is organized by the input library. Subroutines specific to the spectrum and consistent with the input library are found here.

Joystick Functions

uint in_JoyFuller(void)

uint in_JoyKempston(void)

uint in_JoySinclair1(void)

uint in_JoySinclair2(void)

uint in_JoyTimex1(void)

uint in_JoyTimex2(void)

Mouse Functions

AMX Mouse

The AMX mouse is designed to operate in the z80's interrupt mode 2. To use the AMX Mouse you must set up im2 mode (see the im2 library for details) and, with interrupts disabled, call in_MouseAMXInit() with two interrupt vectors upon which the two AMX interrupt service routines will be installed for you. These interrupt vectors must be even since the AMX hardware contains a Z80-PIO chip which can only store even vectors. Any two even vectors will do as long as they don't conflict with any other hardware. On a Spectrum, vectors 0 and 2 are as good as any.

The library also requires that the program declares a few global variables in RAM to hold position data:

unsigned int in_AMXcoordX, in_AMXcoordY, in_AMXdeltaX, in_AMXdeltaY;

The call to in_MouseAMXInit() initializes these variables to sensible values.

in_AMXdeltaX and in_AMXdeltaY control the mouse sensitivity. They are 8.8 fixed point indicating the number of pixels to adjust the mouse coordinates by for each unit of distance the mouse is moved. in_MouseAMXInit() initializes them to 0x80 (1 unit of physical motion = 1 pixel of movement on screen).

void in_MouseAMXInit(uchar xvector, uchar yvector)

void in_MouseAMX(uchar *buttons, uint *xcoord, uint *ycoord)

void in_MouseAMXSetPos(uint xcoord, uint ycoord)

Kempston Mouse

The library requires that the program declare a few global variables in RAM to hold position data:

uchar in_KempcoordX, in_KempcoordY, in_KemprawX, in_KemprawY;

These variables are initialized when in_MouseKempInit() is called.

void in_MouseKempInit(void)

void in_MouseKemp(uchar *buttons, uint *xcoord, uint *ycoord)

void in_MouseKempSetPos(uint xcoord, uint ycoord)

Display Functions

Borrowed From Sinclair Basic

void zx_border(uchar colour)

Set the border colour. Use one of the attribute constants defined at the start of the header (BLACK, BLUE, etc). Changing the border colour involves an OUT to port $fe, which also controls the internal speaker. If your program contains beeper output this may result in an audible click if the OUT happens to toggle the speaker output bit. The library cannot avoid this as it is not known what the last output to the speaker was; to avoid this the program can keep track of the last bit output to the speakerand OR it with the desired border colour in a call such as border(RED | last_speaker_bit); For most programs this is a non-issue.

uint zx_attr(uchar row, uchar col)

Return the attribute on screen of the character coordinate given. Works just like the Basic ATTR() command.

uint zx_screenstr(uchar row, uchar col)

Return the ascii character code for the character printed on screen at the character coordinate given, if any. If an ascii character is not recognized at that position zero is returned. This function is similar to Basic's SCREEN$() command but will also match characters if the bitmap on screen is a mixture of inverted and non-inverted patterns (the basic command will only match if the character is either inverted or not-inverted on screen, but not a mixture). Currently does not match the spectrum's block graphics.

Display Address Manipulators

A collection of functions designed to make access to the Spectrum's display file easy and fast.

In the following, screen address refers to the pixel address within the display file (16384-22527) and attribute address refers to an address in the attributes area (22528-23295).

Function names are constructed from the following atoms:

saddr = screen address
aaddr = attribute address
 
px    = pixel x coordinate (0..255)
py    = pixel y coordinate (0..191)
pxy   = pixel (x,y) coordinate

cx    = character x coordinate (0..31)
cy    = character y coordinate (0..23)
cyx   = character (y,x) coordinate - ordering borrowed from Sinclair Basic

So for example:

  • zx_saddr2cy(saddr) will return the character y coordinate corresponding to the given screen address
  • zx_saddr2aaddr(saddr) will return the attribute address corresponding to the given screen address
  • zx_pxy2aaddr(px,py) will return the attribute address corresponding to the given (x,y) pixel coordinate

Some functions will return with carry flag set if coordinates or addresses move out of bounds. In these cases the special z88dk keywords iferror() and ifnerror() can be used to test the carry flag and determine if results are valid. Functions that do this are documented as such below.

Screen Address Manipulators (pixels)

uchar *zx_cyx2saddr(uchar row, uchar col)

uchar *zx_cy2saddr(uchar row)

uchar *zx_pxy2saddr(uchar xcoord, uchar ycoord, uchar *mask)

uchar *zx_py2saddr(uchar ycoord)

uint zx_saddr2cx(void *pixeladdr)

uint zx_saddr2cy(void *pixeladdr)

uint zx_saddr2px(void *pixeladdr, uchar mask)

uint zx_saddr2py(void *pixeladdr)

uchar *zx_saddr2aaddr(void *pixeladdr)

uchar *zx_saddrcdown(void *pixeladdr)

uchar *zx_saddrcleft(void *pixeladdr)

uchar *zx_saddrcright(void *pixeladdr)

uchar *zx_saddrcup(void *pixeladdr)

uchar *zx_saddrpdown(void *pixeladdr)

uchar *zx_saddrpleft(void *pixeladdr, uchar *mask)

uchar *zx_saddrpright(void *pixeladdr, uchar *mask)

uchar *zx_saddrpup(void *pixeladdr)

Attribute Address Manipulators (attr)

uchar *zx_cyx2aaddr(uchar row, uchar col)

uchar *zx_cy2aaddr(uchar row)

uchar *zx_pxy2aaddr(uchar xcoord, uchar ycoord)

uchar *zx_py2aaddr(uchar ycoord)

uint zx_aaddr2cx(void *attraddr)

uint zx_aaddr2cy(void *attraddr)

uint zx_aaddr2px(void *attraddr)

uint zx_aaddr2py(void *attraddr)

uchar *zx_aaddr2saddr(void *attraddr)

uchar *zx_aaddrcdown(void *attraddr)

uchar *zx_aaddrcleft(void *attraddr)

uchar *zx_aaddrcright(void *attraddr)

uchar *zx_aaddrcup(void *attraddr)

library/zxspectrum.txt · Last modified: 2017/03/25 09:01 (external edit)