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

These are the defined constants for the BASIC KEYWORDS

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.

TRUE if in Spectrum 128 mode

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

Identifies your Spectrum type

Identifies your Spectrum model:

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

Computes the current size of the BASIC variables area.

Returns TRUE if the ZX Printer is attached.

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

Returns TRUE if a Kempston Joystick interface is connected.

Returns TRUE if an ISS Joystick interface is connected.

Returns TRUE if a Disciple / D interface is connected

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

Returns TRUE if TRDOS is active.

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

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

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

Load the specified BASIC string variable into *value.

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

Return the integer value for the specified BASIC numeric variable.

Copies "value" to the specified BASIC variable.

*variable should be set with the BASIC variable name.

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

Copies "value" (double type format) to the specified BASIC variable, creating it if necessary.

*variable must be set with the BASIC variable name.

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

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

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).

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.

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.

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

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.

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.