Classic TMS9918 - z88dk/z88dk GitHub Wiki

The TMS9918a/TMS9928a VDP chip is used by the following targets supported by z88dk:

The classic library supplies a library, based on the Hitech-C library by Rafael de Oliveira Jannone. The library provides both high- and low-level access to the VDP chip using the header <video/tms99x8.h>. The following features are supported:

  • ANSI vt100 console using VDP mode 2
  • vt52 console using VDP modes 0,1,2
  • High resolution graphics (256x192), multicolour graphics (64x48)
  • Entering "mangled" mode
  • Raster interrupt handler
  • Sprite control

For targets with a V9938, <video/v9938.h> is available with additional features.

VDP Screen Modes

The VDP screen modes use the following VDP addresses across all targets:

z88dk Mode MSX Screen Text Resolution Graphics Resolution Pattern Name Colour table Pattern Generator Sprite Generator Sprite Attribute Sprite Mode
0 SCREEN 0 40x24 - $0000 $800 - - -
1 SCREEN 1 32x24 - $1800 $2000 $0000 $3800 $1b00 1
2 SCREEN 2 32x24 256x192 $1800 $2000 $0000 $3800 $1b00 1
3 SCREEN 3 - 64x48 $800 - $0000 $3800 $1b00 1
81 (mangled 1_2 mode) - 32x24 - $1800 $2000 $0000 $3800 $1b00 1

These addresses and mode names match with the MSX convention

V9938 Screen Modes

The library has been extended to support the additional screen modes available on the V9938. At present, only the MSX2 and Einstein 256 are supported, but should another target that supports the chip becomes known, it can be easily extended.

z88dk Mode MSX Screen Text Resolution Graphics Resolution Pattern Name Colour table Pattern Generator Sprite Generator Sprite Attribute Sprite Mode
80 SCREEN 0: TEXT 80 80x24 - $0000 $0800 $1000 - - -
4 SCREEN 4 32x24 256x192 $1800 $2000 $0000 $3800 $1b00 2
5 SCREEN 5 32x24 256x192 $0000 - - $7a00 $7600 2
6 SCREEN 6 64x24 256x192 (*) $0000 - - $7a00 $7600 2
8 SCREEN 8 32x24 256x192 $0000 - - $f000 $fa00 2

(*) Mode6 works in so called fatpix mode which ensures the aspect ratio looks correct at the loss of horizontal resolution.

Mode 0 (Text 40x24)

Mode 0 is supported by the generic console and can be switched to using int mode = 0; console_ioctl(IOCTL_GENCON_SET_MODE, &mode);

The font used is that defined by -pragma-redirect:CRT_FONT=..., when the font is changed programmatically using console_ioctl(IOCTL_GENCON_SET_FONT32,...) all characters on screen will change. Character codes 32-127 (inclusive) are taken from the specified font, leaving the ranges 0-31 and 128-255 available for your own usage.

In this mode, sprites are not supported. When switching to this mode, the current conio ink/paper is taken as the colour for the whole screen. It is possible to change it by writing to the appropriate VDP register.

Mode 1 (Text 32x24)

Mode 1 is supported by the generic console and can be switched to using int mode = 1; console_ioctl(IOCTL_GENCON_SET_MODE, &mode);

The font used is that defined by -pragma-redirect:CRT_FONT=..., when the font is changed programmatically using console_ioctl(IOCTL_GENCON_SET_FONT32,...) all characters on screen will change. Character codes 32-127 (inclusive) are taken from the specified font, leaving the ranges 0-31 and 128-255 available for your own usage

The current attributes are set for all characters. If you wish to change them you should vpoke() addresses in the colour table defined above.

In this mode, sprites are supported. When switching to this mode, the current conio ink/paper is applied to the entire character set. With the table addresses above it is possible for an application to change them.

Mode 2 (Text 32x24, Graphics 256x192)

Mode 2 is supported by the generic console and can be switched to using int mode = 2; console_ioctl(IOCTL_GENCON_SET_MODE, &mode);

The font used is that defined by -pragma-redirect:CRT_FONT=..., it is possible to change the font programmatically using console_ioctl(IOCTL_GENCON_SET_FONT32,...) and have multiple fonts displayed on screen.

In this mode, sprites are supported. Screen scrolling in this mode is notably slower than in the other modes.

Mode 3 (Multicolour, graphics 64x48)

Mode 3 can be switched to, however text is not supported in this mode. The monochrome graphics library can be used, with the pixel colour changed using textcolour()

In this mode, sprites are supported.

Mode 1_2 (mangled mode)

Enter this mode using vdp_set_mangled_mode().

Removing code for unused screen modes

A compilation for a VDP target that uses the ansi terminal, generic console, or graphics will by default include code for setting all of the available screen modes. It's possible to avoid linking code for screen modes that your application doesn't use by specifying one, or any of the following pragmas:

  • -pragma-define:CLIB_DISABLE_MODE0=1 (or #pragma define CLIB_DISABLE_MODE0=1)
  • -pragma-define:CLIB_DISABLE_MODE1=1 (or #pragma define CLIB_DISABLE_MODE1=1) - also disables "mangled"/1_2 mode
  • -pragma-define:CLIB_DISABLE_MODE2=1 (or #pragma define CLIB_DISABLE_MODE2=1)
  • -pragma-define:CLIB_DISABLE_MODE3=1 (or #pragma define CLIB_DISABLE_MODE3=1)

And so on for the V9938 modes as well.

Raster interrupt

Calling add_raster_int() will add an interrupt connected to the VDP interrupt on all platforms except for the Adam running CP/M.

Firmware implementation

On the MSX 1 and SVI machines, it is possible to use the firmware to drive the VDP using the library -lmsxbios