Skip to content

Classic Overview

suborb edited this page Jul 16, 2019 · 16 revisions

Standard Library

The classic library can be used with both sccz80 and zsdcc and the final binary can be made of object files generated by either compiler (subject to floating point not being used).

Classic library vs new library

Originally, the classic library and new library were completely different code bases, however over time they have converged with the result that the only differences are as follows:

  • Classic supports many more targets and has different way of implementing the crt0 startup file
  • <stdio.h> is a different implementation that supports file io
  • Classic supports multiple floating point libraries for pure sccz80 compilations
  • Classic provides the cross platform libraries detailed below
  • Classic tends to be tuned at link time, newlib at library build time

Generic console (vt52)

The generic console console driver provides a uniform set of escape codes to control text positioning, attributes etc. It is integrated into <stdio.h> and if not enabled as the default can be selected with the command line --generic-console.

Floating Point Maths

Multiple maths libraries are available in the classic library. See Classic Maths Libraries.

Three generic maths libraries are available with the classic library genmath, math48 and [bbcmath][]

genmath and math48 perform roughly identically and have the same amount of precision (40 bit mantissa, 8 bit exponent), however the register usage of the libraries is different. genmath uses the ix register and in particular the undocumented opcodes that use ixl and ixh. As a result, it cannot be used on either Rabbit or Z180 processors. math48 on the other hand makes extensive use of the alternate register set.

bbcmath_ provides a 32 bit mantissa, 8 bit exponent and is generally faster than the 40bit libraries. It does however make extensive use of the alternate register set and may not be suitable for all targets.

The ZX Spectrum, ZX81, CPC and z88 platforms additionally provide a maths library that utilises the floating point calculator within their ROMs. These provide a lower degree of precision (a 32 bit mantissa), the trade-off being that they use less of your application memory.

The Microsoft 32 bit and 64 bit maths libraries are supported for machines that run Microsoft BASIC and the appropriate entry points discovered.

The math32 math library provides a 32 bit float format that is mostly compliant with IEEE-754 32 bit floating point. This is the native format for zsdcc floating point. The library supports both z180 and ZX Spectrum Next hardware multiply instructions, as well as supporting z80 platforms using software multiply.

SDCC compatibility: Only -lmath48 and -lmath32 are supported for zsdcc compilations.

Regular Expressions

Simplified regex support is supplied for all platforms.

Memory Allocation

The classic library provides several memory allocators, the easiest way to get started is to use the auto malloc feature of the library. In this mode the crt automatically sets aside a set amount memory between the end of the program and (usually) the stack pointer for the heap. There are a number of presets available: -DAMALLOC will reserve 75% of the free memory, -DAMALLOC2 will reserve 50% of the free memory and -DAMALLOC1 will reserve 25%.

The classic library additionally provides named heap and block allocators.

Sound Libraries

The classic library supports both a 1 bit <sound.h> and a PSG <psg.h> based sound interface.

The 1 bit library defines a collection of sound effects in addition to a tone generator.

Input Library

Hardware keyboard scanning bypasses the target's ROM and directly polls the keyboard. The keyboard routines in_LookupKey and in_Keypressed handle multiple keys being pressed concurrently and as such are ideal for portable games programming. The various routines are defined in <input.h>

On ports where it is available, you can switch stdin to non-firmware reading routines using the option -pragma-redirect:fgetc_cons=fgetc_cons_stdin or the command line alias --hardware-keyboard

Joystick support

Targets generally support at least some form of joystick support. Polling of the joystick is exposed using the joystick() function in <games.h>

There are the following effective levels of support:

  • Two keyboard joysticks using ROM functions: Only a single direction can be registered at once
  • Multiple keyboard joysticks using inkey driver: Multiple directions supported
  • Hardware joystick support: Multiple directions supported

Debug Library

Graphics Libraries

Mono Graphics

A variety of drawing primitives and higher level functions are supplied by <graphics.h>.

Mono Sprites

Software driven mono sprites are available on all platforms with graphics. Some platforms, for example the ZX Spectrum, have more optimised sprite libraries available offering additional features.

X11 emulation

This is an experimental library to emulate some basic behaviour fo the Xlib functions. It isn't based on the network layer as the original library, and it implements only a tiny subset of the original functions but, being based on the "monochrome graphics" library, it is faily portable to many of the supported targets.


The 3D Libraries include a standard set of functions for making your own 3D functions. This document is a reference for these functions. 'lib3d' includes also functions requiring a fast trigonometry approximation, e.g. to draw polygons or for "turtle graphics".

VDP Support

The TMS9918a/TMS9928a VDP is used by a number of targets supported by z88dk. A common library is available across all of those targets allowing both high- and low- level access to the chip.

SP1 Sprite Library

The ZX Spectrum and clones support the sp1 sprite library that provides advanced features ideal for writing performant games.

Interrupt Handling

The library provides functionality to implement general purpose interrupts without having to drop down to machine code.

Preemptive multitasking

A simple preemptive multitasking driver is available in [<threading/preempt.h> this allows multiple tasks to concurrently execute (for example a game simulation and the user interaction) without the need to implement coroutines.

Serial (RS232)

Abstract Data Types (adt)

The library provides ready-to-use abstract data types that implement common data structures in an optimal manner.


Emulation Libraries

The classic library provides both MS-DOS emulation and Turbo C BGI Emulation to assist the porting of software.

Clone this wiki locally
You can’t perform that action at this time.