SDK reference

Everything the SDK offers, grouped by topic: the functions of the system (the API), the graphics engine, the registers and constants of the machine, the memory map and the file formats. To learn how to use them, read the SDK guide and Graphics.

Contents

• The files of the SDK
• Conventions
• System and timing
• Screen and text
• Keyboard, joystick and mouse
• Sound
• Music and effects
• Files and folders
• Clock and language
• Ending a program and running others
• Graphics engine
• .gfx graphics files
• Video registers
• Input registers
• Sound registers
• System variables
• Error codes
• API function numbers
• Memory map
• The .zxv file format
• Tools
• The standard C library (picolibc)
• Internal definitions

The files of the SDK#

Conventions#

• All functions follow the standard RISC-V ilp32 calling convention; the inline functions of the headers call the ROM through the API table.
• Functions that can fail return an int: 0 or more on success and a negative error code on failure.
• "The drawing page" is the video page chosen with zxv_gfx_draw_page (0 at the start of a program); "the visible page" is the one chosen with zxv_set_page.
• Registers are memory: read and write them through volatile pointers, for example *(volatile uint8_t *)(uintptr_t)ZXV_V_BORDER = 2;. Video registers take effect at the next VBLANK.

System and timing#

zxv_wait_vblank#

void zxv_wait_vblank(void);

Waits for the next VBLANK, the start of a frame (60 per second). It turns interrupts on if they were off. Do not call it from a frame hook.

zxv_set_frame_hook#

void zxv_set_frame_hook(void (*fn)(void));

Makes the system call fn at every VBLANK, with interrupts off; 0 removes it. The function must be short and cannot call zxv_wait_vblank. Remove it before your program ends. Variables shared with the hook must be volatile.

zxv_time_us#

uint32_t zxv_time_us(void);

A microsecond counter. It wraps round every 2³² µs (about 71 minutes): compare times by subtracting them as unsigned numbers.

uint32_t t0 = zxv_time_us();
do_something();
uint32_t elapsed = zxv_time_us() - t0;

zxv_api_version#

uint32_t zxv_api_version(void);

The version of the machine specification, as major << 16 | minor (currently 1, version 0.1); the same as ZXV_SPEC_VERSION and the system variable ZXV_SV_VERSION.

Constants#

Screen and text#

zxv_set_mode#

void zxv_set_mode(int mode);

Changes the video mode (0: 256 × 192; 1: 512 × 384) and clears the drawing page with the paper colour of the text (see zxv_text_colors). Only bit 0 of mode counts.

zxv_set_page#

void zxv_set_page(int page);

Makes page 0 or 1 visible from the next VBLANK (writes ZXV_V_PAGE).

zxv_cls#

void zxv_cls(int colour);

Fills the drawing page with a colour (0–15) and moves the text cursor to the top left.

zxv_plot#

void zxv_plot(int x, int y, int colour);

Sets one pixel of the drawing page. Points outside the page are ignored.

zxv_print_char, zxv_print_str#

void zxv_print_char(int c);
void zxv_print_str(const char *s);

Print a character or a zero-terminated string at the text cursor of the drawing page, in cells of 8 × 8 pixels, with the colours of zxv_text_colors. '\n' and '\r' go to the start of the next line, '\b' deletes the previous character, and the screen scrolls up when the text reaches the bottom.

zxv_print_char takes a Unicode code point and zxv_print_str a string in UTF-8 (the encoding of C source files, so you can write "¡Hola!" in your program). They draw the ASCII characters 32 to 126, ©, and the Spanish letters of the ROM's font: á é í ó ú ü ñ, their capitals Á É Í Ó Ú Ü Ñ, ¿ and ¡. Any other character prints as ?.

zxv_text_colors, zxv_text_at#

void zxv_text_colors(int ink, int paper);
void zxv_text_at(int col, int row);

zxv_text_colors sets the colours (0–15) of the text that zxv_print_char and zxv_print_str write from then on: each cell is filled with paper and the character drawn in ink. Every program starts with black on white (0 and 7), whatever the previous one left.

zxv_text_at moves the text cursor to column col and row row, counted from 0 at the top left: 32 × 24 cells in mode 0, 64 × 48 in mode 1. zxv_cls and zxv_set_mode also put the cursor back at the top left.

zxv_text_colors(14, 1);                 /* bright yellow on blue */
zxv_text_at(8, 10);
zxv_print_str("¡Hola, señor Núñez!");

Palette#

The bits of the number are bright, green, red, blue (from bit 3 to bit 0).

These are the palettes' colours at start. Each remapping table has its own palette of 16 RGB565 colours (u16: red in bits 15–11, green in 10–5 and blue in 4–0) at ZXV_PALETTE(t), which can be changed: see Video registers. ZXV_RGB(r, g, b) gives the RGB565 of a colour with components from 0 to 255 (215, D7, is the normal level: ZXV_RGB(215, 0, 0) is red) and ZXV_STD_RGB565(i), index i's usual colour.

Keyboard, joystick and mouse#

zxv_key_get#

int zxv_key_get(void);

Takes the next key from the key queue (64 entries), or returns −1 if it is empty. Keys held down repeat (after 500 ms, 20 times a second).

Ctrl+Alt+Delete never arrives: it returns to BASIC.

zxv_joy_read#

uint32_t zxv_joy_read(int n);

The state of gamepad n (0 or 1; the first one connected is 0). A disconnected gamepad reads 0.

Direction comes from the d-pad or the left stick. On a PlayStation pad, ✕, ○ and □ are fire 1, 2 and 3; Share/Create is Select and Options is Start. On a generic pad, buttons 1–3 are the fire buttons, 9 is Select and 10 Start.

The mouse: zxv_mouse_t, zxv_mouse_init, zxv_mouse_update#

typedef struct {
    int x, y;                   /* the pointer, in pixels */
    int wheel;                  /* the wheel, accumulated (positive upwards) */
    uint8_t buttons;            /* bits 0-2: left, right and middle */
    uint16_t rx, ry;            /* internal: the counters at the last update */
    uint8_t rw;
} zxv_mouse_t;

void zxv_mouse_init(zxv_mouse_t *p, int x, int y);
void zxv_mouse_update(zxv_mouse_t *p, int w, int h);

zxv_mouse_init puts the pointer at (x, y) and remembers the mouse's counters. zxv_mouse_update, once per frame, adds the movement since the last call (one mouse unit is one pixel, without acceleration) and keeps the pointer inside [0, w) × [0, h). It reads the input registers ZXV_I_MOUSE_... directly.

Sound#

zxv_ay_write#

void zxv_ay_write(int reg, int val);

Writes val to register reg of an AY: 0–15 for the first chip, ZXV_AY2 + 0–15 (16–31) for the second. The write goes through a queue of 256 entries and sounds a few milliseconds later; if the queue is full, the function waits. Writing register 13 restarts the envelope, as on the real chip.

The tone frequency is 1,773,447.5 / (16 × period) Hz; the envelope repeats every 256 × period / 1,773,447.5 seconds. Both chips start silent.

zxv_beeper_event#

void zxv_beeper_event(int level);

Changes the beeper to level (0, or anything else for 1) at exactly the current time plus ZXV_BEEP_LATENCY_US (2000 µs). Events go through a queue of 256 entries (shared with zxv_ay_event); if it is full, the function waits. For simple sounds you can write the ZXV_S_BEEPER register instead; both ways add up.

zxv_ay_event#

void zxv_ay_event(uint32_t t_us, int reg, int val);

Writes val to AY register reg (0–31, as in zxv_ay_write) at time t_us (in the clock of zxv_time_us) plus 2 ms. Times must go in increasing order: an event waits for the ones before it. If t_us is already past, it sounds at once. If the queue is full, the function waits. It is meant for digitised sound: see the digital example.

zxv_beeper_event_at#

void zxv_beeper_event_at(uint32_t t_us, int level);

Like zxv_beeper_event, but at time t_us (plus 2 ms), with the same rules as zxv_ay_event: times in increasing order. With the music of zxv_music.h playing, which goes 35 ms ahead, the beeper has to do the same: zxv_beeper_event_at(zxv_time_us() + ZXV_MUSIC_AHEAD_US, level).

Constants#

Music and effects#

Declared in zxv_music.h. Build it with the files of sdk/music. The explanations and an example are in the guide.

Modules#

int zxv_music_info(const void *data, uint32_t size, zxv_music_info_t *info);
int zxv_music_play(const void *data, uint32_t size, int flags);
void zxv_music_stop(void);
void zxv_music_pause(int on);
int zxv_music_playing(void);
uint32_t zxv_music_steps(void);
void zxv_music_moved(const void *song, const void *bank);
void zxv_music_update(void);
void zxv_music_update_until(uint32_t t_us);

• zxv_music_play starts playing a module and returns its format. If it does not know it, it returns ZXV_MUSIC_NONE and plays nothing. flags: ZXV_MUSIC_LOOP (at the end, it goes on from its loop position) and ZXV_MUSIC_AY2 (a one-AY module plays on the second chip).
• zxv_music_info gives the format, title and author of a module, without playing it.
• zxv_music_pause(1) pauses the music and zxv_music_pause(0) resumes it. zxv_music_playing returns 1 while it plays; zxv_music_steps, the 1/50 s steps it has played.
• zxv_music_update prepares the steps of the next ZXV_MUSIC_AHEAD_US (35 ms): call it every frame, or from the frame hook. zxv_music_update_until(t) prepares only those before t, to mix the music with your own zxv_ay_event calls.
• The module and the bank must stay in memory while they play. If the program moves them, it tells the library with zxv_music_moved(module, bank) (NULL for the one that did not move).

typedef struct {
    int format;                 /* ZXV_MUSIC_... */
    int chips;                  /* the AY chips it uses: 1 or 2 */
    char title[33];
    char author[33];
} zxv_music_info_t;

AYFX effects#

int zxv_sfx_bank(const void *data, uint32_t size);
int zxv_sfx_play(int n, int channel);
int zxv_sfx_play_data(const void *data, uint32_t size, int channel);
void zxv_sfx_stop(int channel);
void zxv_sfx_channels(int mask);
int zxv_sfx_playing(int channel);

The channels are 0 to 2 (A, B and C of the first AY) and 3 to 5 (those of the second).

• zxv_sfx_bank sets the effect bank (.afb) and returns how many effects it has.
• zxv_sfx_play plays effect n of the bank on a channel. With ZXV_SFX_AUTO, on a free one (if there is none, on the one that has been playing longest). It returns the channel, or −1 if the effect does not exist. zxv_sfx_play_data does the same with a single effect (.afx).
• zxv_sfx_stop stops the effect on a channel, or all of them with ZXV_SFX_AUTO. zxv_sfx_playing returns 1 if an effect plays on the channel (or on any, with ZXV_SFX_AUTO).
• zxv_sfx_channels picks the channels for ZXV_SFX_AUTO (bit n, channel n). By default, those of the AY the music does not use.

Constants#

Files and folders#

Paths may start with a drive: SD: (the SD card) or ROM: (the read-only built-in drive), upper or lower case; ROM:game is the same as ROM:/game. Without a drive, a path is relative to the current folder, or absolute if it starts with /. . and .. work, and .. at the root stays at the root. Case does not matter. Names have up to 63 printable ASCII characters (not \ : * ? " < > |, not ending in a space or a dot); paths, up to 255.

Up to 8 files and 4 folders can be open at once on each drive. Buffers must be in RAM (or, for reading, in the ROM); otherwise the function returns ZXV_E_FAULT. On a real SD card, a file that is open cannot be deleted, renamed or opened again for writing, and hidden or system files do not appear in listings.

zxv_file_open#

int zxv_file_open(const char *name, uint32_t flags);

Opens a file and returns its number, or an error. flags combines:

Opening for writing on ROM: returns ZXV_E_ACCESS.

zxv_file_read, zxv_file_write#

int zxv_file_read(int f, void *buf, uint32_t n);
int zxv_file_write(int f, const void *buf, uint32_t n);

Read or write up to n bytes at the current position and return how many, or an error. zxv_file_read returns 0 at the end of the file. If you read code into memory to run it, execute a fence.i instruction afterwards.

zxv_file_seek#

int zxv_file_seek(int f, int32_t off, int whence);

Moves the position to off bytes from the start (ZXV_SEEK_SET, 0), the current position (ZXV_SEEK_CUR, 1) or the end (ZXV_SEEK_END, 2), and returns the new position.

zxv_file_close#

int zxv_file_close(int f);

Closes the file. Always close files you wrote: that is when everything reaches the card.

zxv_file_load#

int zxv_file_load(const char *name, void *addr, uint32_t max);

Reads a whole file into memory at addr and returns its size. max is the room you have there: if the file is bigger than max bytes, nothing is loaded and the function returns ZXV_E_RANGE. Pass the size of your buffer:

static uint8_t level[8192];
int size = zxv_file_load("level1.dat", level, sizeof(level));
if (size < 0)
    zxv_report_error(size, "Cannot load level1.dat");

Earlier versions of the SDK had no max argument; a program compiled with them must be compiled again.

zxv_file_stat#

int zxv_file_stat(const char *name, zxv_dirent_t *e);

Fills *e with the name, size and attributes of a file or folder.

typedef struct {
    char name[64];              /* zero-terminated */
    uint32_t size;              /* in bytes */
    uint32_t attr;              /* ZXV_ATTR_DIR (bit 0): it is a folder */
} zxv_dirent_t;

The same 72 bytes described for assembly: ZXV_DIRENT_SIZE (72), ZXV_DE_NAME (0), ZXV_DE_SIZE (64), ZXV_DE_ATTR (68).

zxv_file_remove, zxv_file_rename#

int zxv_file_remove(const char *name);
int zxv_file_rename(const char *from, const char *to);

Delete a file or an empty folder; rename or move a file or folder.

Folders#

int zxv_dir_make(const char *name);             /* create a folder */
int zxv_dir_change(const char *name);           /* change the current folder */
int zxv_dir_current(char *buf, uint32_t len);   /* the current folder; returns its length */
int zxv_dir_open(const char *name);             /* open a folder to list it ("" = the current one) */
int zxv_dir_read(int d, zxv_dirent_t *e);       /* next entry: 1, or 0 at the end */
int zxv_dir_close(int d);

• zxv_dir_change("ROM:") enters the ROM drive and zxv_dir_change("SD:") goes back to the root of the card.
• zxv_dir_current gives /... on the card and ROM:/... on the ROM drive; if buf is too small it returns ZXV_E_RANGE.
• zxv_dir_read returns the entries in alphabetical order, ignoring case.

Constants#

Clock and language#

zxv_clock_get, zxv_clock_set#

typedef struct {
    uint16_t year;                      /* 2000-2099 */
    uint8_t month, day, hour, min, sec;
    uint8_t wday;                       /* 1 Monday ... 7 Sunday (set by clock_get) */
} zxv_clock_t;

int zxv_clock_get(zxv_clock_t *c);
int zxv_clock_set(const zxv_clock_t *c);

zxv_clock_get returns 0, or ZXV_E_NOCLOCK if the clock has not been set (then *c is unchanged). zxv_clock_set returns 0, or ZXV_E_INVAL for a date that does not exist or is outside 2000–2099; it ignores wday. The time is local time, without time zones. Both are slow: to measure time, use zxv_time_us or ZXV_SV_FRAMES. Files created on the card get this date.

For assembly: ZXV_CLOCK_SIZE (8) and the offsets ZXV_CK_YEAR (0), ZXV_CK_MONTH (2), ZXV_CK_DAY (3), ZXV_CK_HOUR (4), ZXV_CK_MIN (5), ZXV_CK_SEC (6), ZXV_CK_WDAY (7).

zxv_lang_get, zxv_lang_set#

uint32_t zxv_lang_get(void);
int zxv_lang_set(uint32_t lang);

The machine's language: a two-letter ISO 639-1 code in lower case, first letter in the low byte, made with ZXV_LANG(a, b). ZXV_LANG_EN is ZXV_LANG('e', 'n') and ZXV_LANG_ES is ZXV_LANG('e', 's'). The ROM has English and Spanish texts, but any code is valid, so programs can use it to choose their own texts. zxv_lang_set changes it (and the machine remembers it); it returns ZXV_E_INVAL if the code is not two lower-case letters.

const char *hello = zxv_lang_get() == ZXV_LANG_ES ? "Hola" : "Hello";

Ending a program and running others#

zxv_exit_to_basic#

void zxv_exit_to_basic(int code);

Ends the program from anywhere and returns to BASIC, as returning code from main does. 0 means success: BASIC shows 0 OK, 0:1. Any other code means an error, and BASIC shows W Native code error (code), 0:1 (in Spanish, W Error en el código nativo (code), 0:1). In both cases the BASIC program that was in memory is gone, because the native program used that memory.

The value main returns works the same way. Native code called from BASIC with USR is different: what it returns is just the value of USR.

zxv_exec#

int zxv_exec(const char *name, int *result);

Loads and runs a .zxv (if name has no extension and does not exist, .zxv is added), stores in *result what it returned, and returns 0 or an error (ZXV_E_FORMAT if it is not a valid program, ZXV_E_RANGE if it does not fit).

A native program cannot use it: called from a .zxv, it returns ZXV_E_ACCESS (−9) and does nothing. Every program is loaded at the same address, at the start of the user RAM, so the new one would overwrite the one that called it. Only BASIC (with LOAD) and the system's monitor launch programs.

zxv_report_error#

void zxv_report_error(int code, const char *msg);

Ends the program and returns to BASIC with the report W and your own message instead of BASIC's: msg is a string in UTF-8, of which BASIC shows up to 47 bytes. If code is not 0, it follows in brackets. For example, zxv_report_error(5, "Fichero dañado") gives W Fichero dañado (5), 0:1, and zxv_report_error(0, "No level files") gives W No level files, 0:1. The message is copied before BASIC takes back the memory, so it can be in a local array. An empty message shows BASIC's usual text (W Native code error (5), 0:1).

BASIC's screen font has the Spanish letters, so ñ, ¿ or á can go in the message; other non-ASCII characters show as ?.

Graphics engine#

Declared in zxv_gfx.h. See Graphics for explanations and examples. All functions draw on the current target and clip to it and to the clip rectangle.

Types#

typedef struct {            /* a bitmap */
    uint8_t *pix;           /* first pixel, aligned to 4 */
    uint16_t stride;        /* bytes per line, a multiple of 4 */
    uint16_t w, h;          /* in pixels */
    uint16_t reserved;
} zxv_bitmap;

typedef struct {            /* a tile map */
    const uint16_t *cells;  /* cells, row by row */
    uint16_t w, h;          /* in cells */
    const uint8_t *tiles;   /* tile graphics, one after another (32 or 128 bytes) */
    uint8_t size;           /* tile side: 8 or 16 */
    uint8_t flags;          /* ZXV_MAP_WRAP */
} zxv_tilemap;

typedef struct {            /* a mode 7 texture */
    const uint8_t *texels;  /* 1 byte per texel (0-15), row by row */
    uint8_t log2size;       /* side = 2^log2size (1 to 10) */
    uint8_t wrap;           /* 1: repeats; 0: outside is colour 'out' */
    uint8_t out;
    uint8_t reserved;
} zxv_m7tex;

typedef struct { int32_t u, v, du, dv; } zxv_m7line;   /* 16.16 fixed point */

typedef struct {            /* a mode 7 camera, 16.16 fixed point */
    int32_t x, y;           /* position on the texture */
    int32_t height;         /* height above the floor */
    int32_t angle;          /* 0x10000 = a full turn; 0 looks towards growing u */
    int32_t focal;          /* focal distance, in pixels */
    int16_t horizon;        /* screen line of the horizon (integer) */
    int16_t reserved;
} zxv_m7cam;

Pixels are 4 bits, two per byte, the even pixel in the low 4 bits. Bitmaps, tiles and prepared sprites must be aligned to 4 bytes.

Constants#

Target and clipping#

void zxv_gfx_target(const zxv_bitmap *b);
void zxv_gfx_draw_page(int page);
void zxv_gfx_clip(int x0, int y0, int x1, int y1);

• zxv_gfx_target(b) makes bitmap b the target; 0 returns to the drawing page. It removes the clip rectangle. The bitmap structure is copied, so it can be a local variable.
• zxv_gfx_draw_page(page) chooses the drawing page (0 or 1), also for zxv_cls, zxv_plot and the text. Its size follows the video mode and ZXV_V_VSIZE.
• zxv_gfx_clip limits drawing to the rectangle from (x0, y0) to (x1, y1), excluding x1 and y1, in target coordinates.

When a program starts, the target is the drawing page 0, without a clip rectangle.

Shapes#

void zxv_gfx_line(int x0, int y0, int x1, int y1, int c);
void zxv_gfx_rect(int x, int y, int w, int h, int c);
void zxv_gfx_tri(const int16_t *p, int c);
void zxv_gfx_poly(const int16_t *p, int n, int c);
void zxv_gfx_circle(int x, int y, int r, int c, int fill);

• zxv_gfx_line: a line including both ends.
• zxv_gfx_rect: a filled rectangle of w × h with its top left corner at (x, y). Nothing if w or h is 0 or less.
• zxv_gfx_tri: a filled triangle; p has 3 pairs x, y.
• zxv_gfx_poly: a filled polygon of n vertices (3 to 64) given as pairs x, y, with the even-odd rule (a five-pointed star drawn in one go has a hole in the middle).
• zxv_gfx_circle: a circle of radius r centred on (x, y): only the outline if fill is 0, a disc otherwise.

Triangles and polygons follow a top-left rule: two of them sharing a side neither overlap nor leave a gap.

Copies#

void zxv_gfx_blit(const zxv_bitmap *src, int sx, int sy, int w, int h, int x, int y, int flags);

Copies the rectangle (sx, sy, w, h) of src to (x, y) of the target, up to 1024 pixels wide. flags: ZXV_FLIP_H, ZXV_FLIP_V, ZXV_BLIT_TRANSPARENT. The part of the rectangle outside src is not copied. Copying a bitmap onto itself with overlapping areas is not defined.

Sprites#

uint32_t zxv_spr_prepare(const zxv_bitmap *src, int sx, int sy, int w, int h, void *buf);
void zxv_spr_draw(const void *spr, int x, int y, int flags, const uint8_t *colours);
void zxv_spr_draw_scaled(const void *spr, int x, int y, int w, int h, int flags, const uint8_t *colours);
int zxv_spr_collide(const void *a, int ax, int ay, const void *b, int bx, int by);

• zxv_spr_prepare converts the rectangle (sx, sy, w, h) of src (up to 1024 × 1024; what falls outside src is transparent) into a sprite in buf, which must be aligned to 4 bytes. It returns the size in bytes, 8 + h × ⌈w / 8⌉ × 8; with buf = NULL it only returns the size. It returns 0 if the size is not valid.
• zxv_spr_draw draws a sprite with its top left corner at (x, y). flags: ZXV_FLIP_H, ZXV_FLIP_V. colours: NULL, or a table of 16 bytes; colour c is drawn as colours[c] (transparent pixels stay transparent).
• zxv_spr_draw_scaled draws it stretched or shrunk to w × h (1 to 4096 each; otherwise nothing), taking for each pixel the nearest one of the sprite. At its own size it is the same as zxv_spr_draw. It uses about 2.5 KB of stack.
• zxv_spr_collide returns 1 if some opaque pixel of a at (ax, ay) coincides with an opaque pixel of b at (bx, by), at their own size.

Tile maps#

void zxv_map_draw(const zxv_tilemap *m, int mx, int my, int x, int y, int w, int h, int filter);
uint16_t zxv_map_cell(const zxv_tilemap *m, int px, int py);

• zxv_map_draw draws, in the rectangle (x, y, w, h) of the target, the part of the map that starts at pixel (mx, my) of the map. filter: ZXV_MAP_ALL, ZXV_MAP_BACK, ZXV_MAP_FRONT. Cells outside a map without ZXV_MAP_WRAP are not drawn. A single call can cover up to 1024 pixels of width.
• zxv_map_cell returns the cell at pixel (px, py) of the map (0 outside a map that does not repeat).

Mode 7#

void zxv_m7_draw(const zxv_m7tex *t, const zxv_m7line *l, int y, int n);
void zxv_m7_camera(zxv_m7line *l, int n, const zxv_m7cam *c);

• zxv_m7_draw draws n lines from line y of the target; line y + i uses l[i]. Pixel x of a line shows the texel at (u + x·du, v + x·dv), taking the integer part of each coordinate.
• zxv_m7_camera fills l[0..n-1] for lines 0 to n−1 of the target: line i below the horizon is at distance height × focal / (i − horizon), with the centre of the target at the camera's x. Lines at or above the horizon are set to zero. Draw with zxv_m7_draw(t, l + y0, y0, n).

.gfx graphics files#

Declared in zxv_gfxfile.h. Build it with gfxfile.c. The explanations, an example and the format are in Graphics.

typedef struct {
    const uint8_t *data;
    uint32_t size;
} zxv_gfxfile;

int zxv_gfxf_open(zxv_gfxfile *f, const void *data, uint32_t size);
const uint8_t *zxv_gfxf_find(const zxv_gfxfile *f, int kind, int num, uint32_t *len);
uint32_t zxv_gfxf_sprite(const zxv_gfxfile *f, int num, zxv_bitmap *b, void *buf, uint32_t room);
uint32_t zxv_gfxf_tiles(const zxv_gfxfile *f, int size, void *buf, uint32_t room, int *count);
uint32_t zxv_gfxf_map(const zxv_gfxfile *f, int num, zxv_tilemap *m, const void *tiles,
                      void *buf, uint32_t room);
uint32_t zxv_gfxf_texture(const zxv_gfxfile *f, int num, zxv_m7tex *t, void *buf, uint32_t room);
uint32_t zxv_gfxf_screen(const zxv_gfxfile *f, int num, int *mode, int *border, void *buf, uint32_t room);
int zxv_gfxf_screen_palette(const zxv_gfxfile *f, int num, uint16_t pal[16]);

• zxv_gfxf_open returns 1 if data is a whole, well-formed .gfx, and leaves f ready; if not, 0. The file can be anywhere: read with zxv_file_load or inside the program.
• The objects in the file are not aligned, so each function copies its object into buf, aligned to 4. It returns the bytes buf needs, or 0 if the object is not there or is not valid. If buf is NULL or room is smaller, it copies nothing: that is how you ask for the size.
• zxv_gfxf_sprite: sprite num as a bitmap (b points to buf).
• zxv_gfxf_tiles: the tiles of side size (8 or 16), one after another. In *count, how many there are (count can be NULL).
• zxv_gfxf_map: the cells of map num, in buf. m gets them and tiles, the tiles of its size (from zxv_gfxf_tiles).
• zxv_gfxf_texture: the texels of mode 7 texture num.
• zxv_gfxf_screen: the pixels of screen num, like those of a VRAM page (24,576 bytes in mode 0, 98,304 in mode 1), and its mode and border in *mode and *border. buf can be the hidden page.
• zxv_gfxf_screen_palette: the 16 RGB565 colours of screen num, to put in ZXV_PALETTE(t). It returns 1 if the screen has a palette; if not, 0 and the usual colours.
• zxv_gfxf_find: an object's data as it is in the file (not aligned) and its length in *len, or NULL if it is not there.

Video registers#

Write them at any time; the system applies them at the next VBLANK.

With scroll, screen pixel (x, y) shows page pixel ((x + SCROLL_X) mod width, (y + SCROLL_Y) mod height).

Page sizes (ZXV_V_VSIZE, mode 0 only; ignored in mode 1):

Remapping tables: four tables of 16 bytes from ZXV_REMAP_TABLES (table t at ZXV_REMAP_TABLES + 16·t). Entry v is the colour shown for pixel value v. They start as the identity.

Palettes: each table has its own, 16 RGB565 colours (u16) from ZXV_PALETTE(t) (ZXV_PALETTES + 32·t, at 0x2000_0480). A pixel of value v on a line that uses table t is shown in colour palette[t][table[t][v]]. They start with the usual colours (ZXV_STD_RGB565), and the ROM sets them again when each program starts. Like the tables, they are read just after each VBLANK.

Line table: at ZXV_LINE_TABLE, one entry of ZXV_LINE_ENTRY_SIZE (8) bytes per line of the whole frame, border included: 240 lines in mode 0 (the picture starts at line 24), 480 in mode 1 (picture from line 48): ZXV_FRAME_LINES(mode) and ZXV_BORDER_LINES(mode). The frame is ZXV_FRAME_W × ZXV_FRAME_H (640 × 480), with a border of ZXV_BORDER_X (64) pixels at each side and ZXV_BORDER_Y (48) lines above and below.

On border lines only the border field counts.

When changes are safe: right after each VBLANK the system reads the visible page, the registers and the tables. While bit ZXV_SYSF_LINK_BUSY of ZXV_SV_SYSFLAGS is 1 (up to 1.5 ms in mode 0 and 6 ms in mode 1 or with a large page), do not write to the visible page or the line table.

Video memory: ZXV_VRAM0_BASE (0x2000_4000) and ZXV_VRAM1_BASE (0x2001_C000), ZXV_VRAM_PAGE_SIZE (96 KB) each.

Input registers#

HID codes of common keys: A–Z 0x04–0x1D; 1–9 0x1E–0x26, 0 0x27; Enter 0x28, Esc 0x29, Backspace 0x2A, Tab 0x2B, Space 0x2C; F1–F12 0x3A–0x45; Insert 0x49, Home 0x4A, Page Up 0x4B, Delete 0x4C, End 0x4D, Page Down 0x4E; Right 0x4F, Left 0x50, Down 0x51, Up 0x52; left Ctrl, Shift, Alt 0xE0–0xE2, right ones 0xE4–0xE6. They identify the position of the key on a US keyboard.

The Spectrum matrix (ZXV_I_KEYROWS[n], bits 0 to 4):

Shift is CAPS SHIFT and Ctrl is SYMBOL SHIFT; Backspace, Esc and the cursor keys press their Spectrum combinations (CAPS SHIFT + 0, SPACE, 5–8), and punctuation signs press SYMBOL SHIFT with the right key.

Sound registers#

The queues are easier to use through zxv_ay_write, zxv_beeper_event and zxv_ay_event.

Stereo mixing: in ABC, left = A + half of B and right = C + half of B; in ACB, left = A + half of C, right = B + half of C; in mono, all three on both sides. The beeper goes to both sides. The channels of the two chips with the same letter are added together.

System variables#

At ZXV_SYSVARS (0x2000_0700), 32 bits each:

Error codes#

If the card is taken out, or stops answering, while files or folders are open, they keep their numbers (a file opened afterwards does not get one of them) and every call on them returns ZXV_E_NOCARD or ZXV_E_IO until you close them. Closing them returns ZXV_OK: what was already written is on the card.

API function numbers#

The API is a table of 256 function addresses at ZXV_API_TABLE (0x2000_0000). Entry n is at ZXV_API_TABLE + 4·n. From C, the headers' functions use the macro ZXV_API_FN(n, type), which reads the entry and casts it to a function pointer type. In assembly:

    lui  t0, %hi(ZXV_API_TABLE)
    lw   t0, 4*ZXV_API_CLS(t0)
    jalr t0

zxv_lang_get and the mouse functions read memory directly and have no number. Unused entries return −1. Because the table is in RAM, a program can replace an entry to intercept a routine.

Memory map#

System area:

The rest of the system area is for the ROM's internal use.

The processor is a 32-bit RISC-V (RV32IMAC with the Zba, Zbb, Zbs, Zbkb and Zcb extensions, -march=rv32imac_zicsr_zifencei_zba_zbb_zbs_zbkb_zcb -mabi=ilp32), little-endian. Unaligned accesses to 16- or 32-bit data stop the program. Programs may turn interrupts on and off (bit 3 of mstatus) and read mcycle/minstret; other control registers belong to the system.

How the SDK lays out a program#

zxv.ld puts, from 0x2003_4000: the code (starting with crt0.S), the constants, the initialised variables, then the zeroed variables (BSS). It defines these symbols:

The stack is the system's: it starts near ZXV_URAM_END and grows down.

The .zxv file format#

A 72-byte header, followed by the loading screen, if there is one, and the program image, which is copied to the load address. All numbers are little-endian.

When loading, the system checks the signature, the header size, the profile, that the load address is aligned to 4 and the entry point inside the image, that image and BSS fit in the user RAM leaving 4 KB below the system stack, and the CRC. Then it clears the BSS, sets the video mode (if the loading screen is not already in that mode) and calls the entry point as int entry(void). A stack top other than 0 must be aligned to 16 and lie between the end of the BSS and ZXV_URAM_END. A .zxv with the old 64-byte header does not load (ZXV_E_FORMAT): run it through elf2zxv.py again.

The loading screen is the data of a screen object of a .gfx:

ZXV_SCREEN_HEAD (4) is the size of the screen's header and ZXV_SCREEN_SIZE_F(mode, flags), the size of the whole screen. The ROM shows it before it loads the image, with its mode, its border and, if it has one, its palette in table 0. If it is in the program's mode, the program starts with it on page 0; if not, in its own mode with a clear screen.

Tools#

elf2zxv.py#

python3 sdk/tools/elf2zxv.py INPUT.elf OUTPUT.zxv [--name NAME] [--mode 0|1] [--stack ADDRESS] [--screen SCREEN]

It checks that the program is inside the user RAM and prints the load address, the entry point and the sizes. Like png2gfx.py, it speaks English, or Spanish if your system is in Spanish.

png2gfx.py#

python3 sdk/tools/png2gfx.py OUTPUT.gfx COMMAND...
python3 sdk/tools/png2gfx.py --list FILE.gfx

The commands are listed in Graphics, together with the .gfx format. Sprite numbers go from 0 to 255, tiles from 0 to 4095, maps from 0 to 15 and textures from 0 to 3, as in BASIC, and screens from 0 to 255. It reads any PNG except interlaced ones, without other Python packages.

The standard C library (picolibc)#

Programs compiled with picolibc and zxvc.c (see the guide) can use:

• API errors arrive in errno (ENOENT, EEXIST, ENOTEMPTY, ENOSPC...; no card is ENODEV).
• Descriptors 0, 1 and 2 are the console; files start at 3.
• struct dirent has d_name, d_type (DT_DIR or DT_REG) and, as an extra, the size in d_size.
• printf with decimals adds about 7 KB; -DPICOLIBC_INTEGER_PRINTF_SCANF when linking uses the smaller one, integers only.
• The console speaks UTF-8, like C strings: printf("¿Qué tal?") shows the accents, and fgets gives the keys typed in UTF-8 (ñ is two bytes). Letters the ROM font does not have come out as ?.

Internal definitions#

zxv.h is shared with the ROM and the emulator, so it also defines things programs must not use: the platform interface (ZXV_PLATFORM_IF and every ZXV_PIF_...), the BASIC debugger's mailbox (ZXV_DBG_BOX and every ZXV_DBG...), the ROM's workspace (ZXV_ROM_WORKSPACE, ZXV_ROM_WORKSPACE_END), the flash addresses (ZXV_FLASH_BASE, ZXV_FLASH_SIZE, ZXV_PLATFORM_BASE, ZXV_ROM_SIZE) and the SRAM ones (ZXV_SRAM_BASE, ZXV_SRAM_SIZE, ZXV_RESERVED_END). They are listed here only so that you recognise them.