Referencia del SDK

Todo lo que trae el SDK, agrupado por temas: las funciones del sistema (la API), el motor gráfico, los registros y las constantes de la máquina, el mapa de memoria y los formatos de fichero. Para aprender a usarlo, lee la guía del SDK y Gráficos.

Contenido

• Los ficheros del SDK
• Convenciones
• Sistema y tiempo
• Pantalla y texto
• Teclado, mando y ratón
• Sonido
• Música y efectos
• Ficheros y carpetas
• Reloj e idioma
• Terminar un programa y ejecutar otros
• Motor gráfico
• Ficheros de gráficos .gfx
• Registros de vídeo
• Registros de entrada
• Registros de sonido
• Variables del sistema
• Códigos de error
• Números de las funciones de la API
• Mapa de memoria
• El formato .zxv
• Herramientas
• La biblioteca estándar de C (picolibc)
• Definiciones internas

Los ficheros del SDK#

Convenciones#

• Todas las funciones siguen la convención de llamada estándar de RISC-V ilp32; las funciones inline de las cabeceras llaman a la ROM a través de la tabla de la API.
• Las funciones que pueden fallar devuelven un int: 0 o más si van bien y un código de error negativo si fallan.
• «La página de dibujo» es la página de vídeo elegida con zxv_gfx_draw_page (la 0 al empezar un programa); «la página visible» es la elegida con zxv_set_page.
• Los registros son memoria: se leen y se escriben con punteros volatile, por ejemplo *(volatile uint8_t *)(uintptr_t)ZXV_V_BORDER = 2;. Los registros de vídeo se aplican en el siguiente VBLANK.

Sistema y tiempo#

zxv_wait_vblank#

void zxv_wait_vblank(void);

Espera al siguiente VBLANK, el principio de un frame (60 por segundo). Activa las interrupciones si estaban desactivadas. No la llames desde un gancho de frame.

zxv_set_frame_hook#

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

Hace que el sistema llame a fn en cada VBLANK, con las interrupciones desactivadas; 0 lo quita. La función debe ser breve y no puede llamar a zxv_wait_vblank. Quítalo antes de que termine tu programa. Las variables que comparta con el gancho deben ser volatile.

zxv_time_us#

uint32_t zxv_time_us(void);

Un contador de microsegundos. Da la vuelta cada 2³² µs (unos 71 minutos): compara tiempos restándolos como números sin signo.

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

zxv_api_version#

uint32_t zxv_api_version(void);

La versión de la especificación de la máquina, como mayor << 16 | menor (ahora 1, la versión 0.1); lo mismo que ZXV_SPEC_VERSION y que la variable del sistema ZXV_SV_VERSION.

Constantes#

Pantalla y texto#

zxv_set_mode#

void zxv_set_mode(int mode);

Cambia el modo de vídeo (0: 256 × 192; 1: 512 × 384) y borra la página de dibujo con el color del papel del texto (ver zxv_text_colors). Solo cuenta el bit 0 de mode.

zxv_set_page#

void zxv_set_page(int page);

Hace visible la página 0 o la 1 desde el siguiente VBLANK (escribe ZXV_V_PAGE).

zxv_cls#

void zxv_cls(int colour);

Llena la página de dibujo con un color (0–15) y lleva el cursor de texto arriba a la izquierda.

zxv_plot#

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

Pinta un píxel de la página de dibujo. Los puntos de fuera de la página se ignoran.

zxv_print_char, zxv_print_str#

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

Escriben un carácter o una cadena terminada en cero en el cursor de texto de la página de dibujo, en celdas de 8 × 8 píxeles, con los colores de zxv_text_colors. '\n' y '\r' van al principio de la línea siguiente, '\b' borra el carácter anterior, y la pantalla sube cuando el texto llega abajo.

zxv_print_char recibe un código Unicode y zxv_print_str, una cadena en UTF-8 (la codificación de los ficheros de C, así que puedes escribir "¡Hola!" en tu programa). Dibujan los caracteres ASCII del 32 al 126, © y las letras del español de la fuente de la ROM: á é í ó ú ü ñ, sus mayúsculas Á É Í Ó Ú Ü Ñ, ¿ y ¡. Cualquier otro carácter sale como ?.

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 elige los colores (0–15) del texto que escriban desde entonces zxv_print_char y zxv_print_str: cada celda se llena con paper (el papel) y el carácter se dibuja con ink (la tinta). Cada programa empieza con negro sobre blanco (0 y 7), deje lo que deje el anterior.

zxv_text_at lleva el cursor de texto a la columna col y la fila row, contadas desde 0 arriba a la izquierda: 32 × 24 celdas en el modo 0 y 64 × 48 en el modo 1. zxv_cls y zxv_set_mode también devuelven el cursor arriba a la izquierda.

zxv_text_colors(14, 1);                 /* amarillo brillante sobre azul */
zxv_text_at(8, 10);
zxv_print_str("¡Hola, señor Núñez!");

La paleta#

Los bits del número son brillo, verde, rojo y azul (del bit 3 al 0).

Son los colores de las paletas al empezar. Cada tabla de remapeo tiene su paleta, de 16 colores RGB565 (u16: rojo en los bits 15–11, verde en los 10–5 y azul en los 4–0) en ZXV_PALETTE(t), que se puede cambiar: ver Registros de vídeo. ZXV_RGB(r, g, b) da el RGB565 de un color de 0 a 255 por componente (215, D7, es el nivel normal: ZXV_RGB(215, 0, 0) es el rojo) y ZXV_STD_RGB565(i), el color de siempre del índice i.

Teclado, mando y ratón#

zxv_key_get#

int zxv_key_get(void);

Saca la siguiente tecla de la cola de teclas (64 entradas), o devuelve −1 si está vacía. Las teclas mantenidas se repiten (a los 500 ms, y luego 20 veces por segundo).

Ctrl+Alt+Supr no llega nunca: vuelve al BASIC.

zxv_joy_read#

uint32_t zxv_joy_read(int n);

El estado del mando n (0 o 1; el primero que se conecta es el 0). Un mando desconectado da 0.

La dirección sale de la cruceta o del stick izquierdo. En un mando de PlayStation, ✕, ○ y □ son los fuegos 1, 2 y 3; Share/Create es Select y Options, Start. En un mando genérico, los botones 1–3 son los fuegos, el 9 es Select y el 10, Start.

El ratón: zxv_mouse_t, zxv_mouse_init, zxv_mouse_update#

typedef struct {
    int x, y;                   /* el puntero, en píxeles */
    int wheel;                  /* la rueda, acumulada (positiva hacia arriba) */
    uint8_t buttons;            /* bits 0-2: izquierdo, derecho y central */
    uint16_t rx, ry;            /* interno: los contadores en la última llamada */
    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 pone el puntero en (x, y) y se queda con los contadores del ratón. zxv_mouse_update, una vez por frame, suma el movimiento desde la llamada anterior (una unidad del ratón es un píxel, sin aceleración) y mantiene el puntero dentro de [0, w) × [0, h). Lee directamente los registros de entrada ZXV_I_MOUSE_....

Sonido#

zxv_ay_write#

void zxv_ay_write(int reg, int val);

Escribe val en el registro reg de un AY: 0–15 para el primer chip, ZXV_AY2 + 0–15 (16–31) para el segundo. La escritura pasa por una cola de 256 entradas y suena unos milisegundos después; si la cola está llena, la función espera. Escribir el registro 13 reinicia la envolvente, como en el chip de verdad.

La frecuencia del tono es 1.773.447,5 / (16 × periodo) Hz; la envolvente se repite cada 256 × periodo / 1.773.447,5 segundos. Los dos chips empiezan en silencio.

zxv_beeper_event#

void zxv_beeper_event(int level);

Pone el beeper a level (0, o cualquier otra cosa para 1) exactamente a la hora actual más ZXV_BEEP_LATENCY_US (2000 µs). Los cambios pasan por una cola de 256 entradas (compartida con zxv_ay_event); si está llena, la función espera. Para sonidos sencillos puedes escribir en el registro ZXV_S_BEEPER; las dos formas se suman.

zxv_ay_event#

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

Escribe val en el registro reg de un AY (0–31, como en zxv_ay_write) a la hora t_us (en el reloj de zxv_time_us) más 2 ms. Las horas deben ir de menor a mayor: un cambio espera a los que tiene delante. Si t_us ya ha pasado, suena enseguida. Si la cola está llena, la función espera. Está pensada para el sonido digitalizado: ver el ejemplo digital.

zxv_beeper_event_at#

void zxv_beeper_event_at(uint32_t t_us, int level);

Como zxv_beeper_event, pero a la hora t_us (más 2 ms), con las mismas reglas que zxv_ay_event: las horas de menor a mayor. Con la música de zxv_music.h sonando, que va 35 ms por delante, el beeper tiene que ir igual: zxv_beeper_event_at(zxv_time_us() + ZXV_MUSIC_AHEAD_US, nivel).

Constantes#

Música y efectos#

Declarado en zxv_music.h. Se compila con los ficheros de sdk/music. Las explicaciones y un ejemplo están en la guía.

Módulos#

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 empieza a tocar un módulo y da su formato. Si no lo reconoce, da ZXV_MUSIC_NONE y no toca nada. flags: ZXV_MUSIC_LOOP (al acabar, sigue por su posición de vuelta) y ZXV_MUSIC_AY2 (un módulo de un AY suena en el segundo).
• zxv_music_info da el formato, el título y el autor de un módulo, sin tocarlo.
• zxv_music_pause(1) para la música y zxv_music_pause(0) la sigue. zxv_music_playing da 1 mientras suena; zxv_music_steps, los pasos de 1/50 s que lleva.
• zxv_music_update prepara los pasos de los próximos ZXV_MUSIC_AHEAD_US (35 ms): llámala en cada frame, o desde el gancho de frame. zxv_music_update_until(t) prepara solo los de antes de t, para mezclar la música con tus zxv_ay_event.
• El módulo y el banco tienen que seguir en la memoria mientras suenan. Si el programa los mueve, se lo dice con zxv_music_moved(módulo, banco) (NULL en el que no se ha movido).

typedef struct {
    int format;                 /* ZXV_MUSIC_... */
    int chips;                  /* los AY que usa: 1 o 2 */
    char title[33];
    char author[33];
} zxv_music_info_t;

Efectos AYFX#

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

Los canales son del 0 al 2 (A, B y C del primer AY) y del 3 al 5 (los del segundo).

• zxv_sfx_bank elige el banco de efectos (.afb) y da cuántos tiene.
• zxv_sfx_play toca el efecto n del banco en un canal. Con ZXV_SFX_AUTO, en uno libre (si no hay, en el que lleva más tiempo sonando). Da el canal, o −1 si el efecto no existe. zxv_sfx_play_data hace lo mismo con un efecto suelto (.afx).
• zxv_sfx_stop para el efecto de un canal, o todos con ZXV_SFX_AUTO. zxv_sfx_playing da 1 si suena un efecto en el canal (o en alguno, con ZXV_SFX_AUTO).
• zxv_sfx_channels elige los canales de ZXV_SFX_AUTO (el bit n, el canal n). Por defecto son los del AY que no usa la música.

Constantes#

Ficheros y carpetas#

Las rutas pueden empezar por una unidad: SD: (la tarjeta SD) o ROM: (la unidad de solo lectura de serie), en mayúsculas o minúsculas; ROM:graphics es lo mismo que ROM:/graficos. Sin unidad, una ruta es relativa a la carpeta actual, o absoluta si empieza por /. . y .. funcionan, y .. en la raíz se queda en la raíz. Las mayúsculas dan igual. Los nombres tienen hasta 63 caracteres ASCII imprimibles (sin \ : * ? " < > |, y sin acabar en espacio ni en punto); las rutas, hasta 255.

Puede haber hasta 8 ficheros y 4 carpetas abiertos a la vez en cada unidad. Los buffers tienen que estar en la RAM (o, para leer, en la ROM); si no, la función devuelve ZXV_E_FAULT. En una tarjeta SD de verdad, un fichero abierto no se puede borrar, renombrar ni volver a abrir para escribir, y los ficheros ocultos o de sistema no salen en los listados.

zxv_file_open#

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

Abre un fichero y devuelve su número, o un error. flags combina:

Abrir para escribir en ROM: devuelve 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);

Leen o escriben hasta n bytes en la posición actual y devuelven cuántos, o un error. zxv_file_read devuelve 0 al final del fichero. Si lees código en memoria para ejecutarlo, ejecuta después una instrucción fence.i.

zxv_file_seek#

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

Lleva la posición a off bytes desde el principio (ZXV_SEEK_SET, 0), la posición actual (ZXV_SEEK_CUR, 1) o el final (ZXV_SEEK_END, 2), y devuelve la nueva posición.

zxv_file_close#

int zxv_file_close(int f);

Cierra el fichero. Cierra siempre los ficheros en los que escribas: es entonces cuando todo llega a la tarjeta.

zxv_file_load#

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

Lee un fichero entero en la memoria, en addr, y devuelve su tamaño. max es el sitio que tienes allí: si el fichero ocupa más de max bytes, no se carga nada y la función devuelve ZXV_E_RANGE. Pásale el tamaño de tu buffer:

static uint8_t nivel[8192];
int tam = zxv_file_load("nivel1.dat", nivel, sizeof(nivel));
if (tam < 0)
    zxv_report_error(tam, "No puedo cargar nivel1.dat");

Las versiones anteriores del SDK no tenían el argumento max; un programa compilado con ellas hay que volver a compilarlo.

zxv_file_stat#

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

Rellena *e con el nombre, el tamaño y los atributos de un fichero o una carpeta.

typedef struct {
    char name[64];              /* terminado en cero */
    uint32_t size;              /* en bytes */
    uint32_t attr;              /* ZXV_ATTR_DIR (bit 0): es una carpeta */
} zxv_dirent_t;

Los mismos 72 bytes, descritos para el ensamblador: 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);

Borran un fichero o una carpeta vacía; cambian el nombre de un fichero o una carpeta, o lo mueven.

Carpetas#

int zxv_dir_make(const char *name);             /* crea una carpeta */
int zxv_dir_change(const char *name);           /* cambia la carpeta actual */
int zxv_dir_current(char *buf, uint32_t len);   /* la carpeta actual; devuelve su longitud */
int zxv_dir_open(const char *name);             /* abre una carpeta para listarla ("" = la actual) */
int zxv_dir_read(int d, zxv_dirent_t *e);       /* la siguiente entrada: 1, o 0 al final */
int zxv_dir_close(int d);

• zxv_dir_change("ROM:") entra en la unidad ROM y zxv_dir_change("SD:") vuelve a la raíz de la tarjeta.
• zxv_dir_current da /... en la tarjeta y ROM:/... en la unidad ROM; si buf es pequeño devuelve ZXV_E_RANGE.
• zxv_dir_read da las entradas en orden alfabético, sin distinguir mayúsculas.

Constantes#

Reloj e idioma#

zxv_clock_get, zxv_clock_set#

typedef struct {
    uint16_t year;                      /* 2000-2099 */
    uint8_t month, day, hour, min, sec;
    uint8_t wday;                       /* 1 lunes ... 7 domingo (lo pone 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 devuelve 0, o ZXV_E_NOCLOCK si el reloj no está en hora (y entonces no toca *c). zxv_clock_set devuelve 0, o ZXV_E_INVAL si la fecha no existe o está fuera de 2000–2099; no mira wday. La hora es la local, sin zonas horarias. Las dos son lentas: para medir tiempos, usa zxv_time_us o ZXV_SV_FRAMES. Los ficheros que se crean en la tarjeta llevan esta fecha.

Para el ensamblador: ZXV_CLOCK_SIZE (8) y los desplazamientos 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);

El idioma de la máquina: un código ISO 639-1 de dos letras minúsculas, la primera en el byte bajo, que se forma con ZXV_LANG(a, b). ZXV_LANG_EN es ZXV_LANG('e', 'n') y ZXV_LANG_ES es ZXV_LANG('e', 's'). La ROM tiene sus textos en inglés y en español, pero cualquier código vale, así que los programas pueden usarlo para elegir los suyos. zxv_lang_set lo cambia (y la máquina lo recuerda); devuelve ZXV_E_INVAL si el código no son dos letras minúsculas.

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

Terminar un programa y ejecutar otros#

zxv_exit_to_basic#

void zxv_exit_to_basic(int code);

Termina el programa desde cualquier sitio y vuelve al BASIC, igual que devolver code desde main. El 0 significa que todo ha ido bien: el BASIC enseña 0 OK, 0:1. Cualquier otro código es un error, y el BASIC enseña W Error en el código nativo (code), 0:1 (en inglés, W Native code error (code), 0:1). En los dos casos el programa BASIC que hubiera en la memoria ha desaparecido, porque el programa nativo ha usado esa memoria.

El valor que devuelve main funciona igual. El código nativo al que se llama desde el BASIC con USR es distinto: lo que devuelve es sin más el valor de USR.

zxv_exec#

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

Carga y ejecuta un .zxv (si name no tiene extensión y no existe, se le añade .zxv), deja en *result lo que devolvió y devuelve 0 o un error (ZXV_E_FORMAT si no es un programa válido, ZXV_E_RANGE si no cabe).

Un programa nativo no puede usarla: llamada desde un .zxv, devuelve ZXV_E_ACCESS (−9) y no hace nada. Todos los programas se cargan en la misma dirección, al principio de la RAM de usuario, así que el nuevo pisaría al que lo llama. Solo el BASIC (con LOAD) y el monitor del sistema lanzan programas.

zxv_report_error#

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

Termina el programa y vuelve al BASIC con el informe W y tu propio mensaje en vez del del BASIC: msg es una cadena en UTF-8, de la que el BASIC enseña hasta 47 bytes. Si code no es 0, va detrás entre paréntesis. Por ejemplo, zxv_report_error(5, "Fichero dañado") da W Fichero dañado (5), 0:1, y zxv_report_error(0, "Faltan los niveles") da W Faltan los niveles, 0:1. El mensaje se copia antes de que el BASIC recupere la memoria, así que puede estar en una matriz local. Un mensaje vacío deja el texto de siempre del BASIC (W Error en el código nativo (5), 0:1).

La fuente de la pantalla del BASIC tiene las letras del español, así que el mensaje puede llevar ñ, ¿ o á; los demás caracteres que no son ASCII salen como ?.

Motor gráfico#

Declarado en zxv_gfx.h. Ver Gráficos para las explicaciones y los ejemplos. Todas las funciones dibujan en el destino actual y recortan contra él y contra el rectángulo de recorte.

Tipos#

typedef struct {            /* un bitmap */
    uint8_t *pix;           /* primer píxel, alineado a 4 */
    uint16_t stride;        /* bytes por línea, múltiplo de 4 */
    uint16_t w, h;          /* en píxeles */
    uint16_t reserved;
} zxv_bitmap;

typedef struct {            /* un mapa de tiles */
    const uint16_t *cells;  /* celdas, fila a fila */
    uint16_t w, h;          /* en celdas */
    const uint8_t *tiles;   /* gráficos de los tiles, seguidos (32 o 128 bytes) */
    uint8_t size;           /* lado del tile: 8 o 16 */
    uint8_t flags;          /* ZXV_MAP_WRAP */
} zxv_tilemap;

typedef struct {            /* una textura del modo 7 */
    const uint8_t *texels;  /* 1 byte por texel (0-15), fila a fila */
    uint8_t log2size;       /* lado = 2^log2size (de 1 a 10) */
    uint8_t wrap;           /* 1: se repite; 0: fuera es del color 'out' */
    uint8_t out;
    uint8_t reserved;
} zxv_m7tex;

typedef struct { int32_t u, v, du, dv; } zxv_m7line;   /* coma fija 16.16 */

typedef struct {            /* una cámara del modo 7, coma fija 16.16 */
    int32_t x, y;           /* posición sobre la textura */
    int32_t height;         /* altura sobre el suelo */
    int32_t angle;          /* 0x10000 = una vuelta; 0 mira hacia u creciente */
    int32_t focal;          /* distancia focal, en píxeles */
    int16_t horizon;        /* línea de la pantalla del horizonte (entera) */
    int16_t reserved;
} zxv_m7cam;

Los píxeles son de 4 bits, dos por byte, el par en los 4 bits bajos. Los bitmaps, los tiles y los sprites preparados tienen que estar alineados a 4 bytes.

Constantes#

Destino y recorte#

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) hace destino al bitmap b; 0 vuelve a la página de dibujo. Quita el rectángulo de recorte. La estructura del bitmap se copia, así que puede ser una variable local.
• zxv_gfx_draw_page(página) elige la página de dibujo (0 o 1), también para zxv_cls, zxv_plot y el texto. Su tamaño sigue al modo de vídeo y a ZXV_V_VSIZE.
• zxv_gfx_clip limita el dibujo al rectángulo de (x0, y0) a (x1, y1), sin incluir x1 ni y1, en coordenadas del destino.

Al empezar un programa, el destino es la página de dibujo 0, sin rectángulo de recorte.

Figuras#

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: una línea con sus dos extremos.
• zxv_gfx_rect: un rectángulo relleno de w × h con la esquina de arriba a la izquierda en (x, y). Nada si w o h valen 0 o menos.
• zxv_gfx_tri: un triángulo relleno; p tiene 3 pares x, y.
• zxv_gfx_poly: un polígono relleno de n vértices (de 3 a 64) dados como pares x, y, con la regla par-impar (una estrella de cinco puntas dibujada de un trazo tiene un hueco en el centro).
• zxv_gfx_circle: un círculo de radio r con centro en (x, y): solo el contorno si fill es 0, y un disco si no.

Los triángulos y los polígonos siguen una regla de arriba a la izquierda: dos que compartan un lado ni se solapan ni dejan huecos.

Copias#

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

Copia el rectángulo (sx, sy, w, h) de src en (x, y) del destino, hasta 1024 píxeles de ancho. flags: ZXV_FLIP_H, ZXV_FLIP_V, ZXV_BLIT_TRANSPARENT. La parte del rectángulo que cae fuera de src no se copia. Copiar un bitmap sobre sí mismo con zonas que se solapan no está definido.

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 convierte el rectángulo (sx, sy, w, h) de src (hasta 1024 × 1024; lo que cae fuera de src es transparente) en un sprite en buf, que tiene que estar alineado a 4 bytes. Devuelve el tamaño en bytes, 8 + h × ⌈w / 8⌉ × 8; con buf = NULL solo devuelve el tamaño. Devuelve 0 si el tamaño no vale.
• zxv_spr_draw dibuja un sprite con la esquina de arriba a la izquierda en (x, y). flags: ZXV_FLIP_H, ZXV_FLIP_V. colours: NULL, o una tabla de 16 bytes; el color c se dibuja como colours[c] (los píxeles transparentes siguen siéndolo).
• zxv_spr_draw_scaled lo dibuja estirado o encogido a w × h (de 1 a 4096 cada uno; si no, nada), tomando para cada píxel el más cercano del sprite. A su tamaño es lo mismo que zxv_spr_draw. Usa unos 2,5 KB de pila.
• zxv_spr_collide devuelve 1 si algún píxel opaco de a en (ax, ay) coincide con un píxel opaco de b en (bx, by), a su tamaño.

Mapas de tiles#

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 dibuja, en el rectángulo (x, y, w, h) del destino, la parte del mapa que empieza en el píxel (mx, my) del mapa. filter: ZXV_MAP_ALL, ZXV_MAP_BACK, ZXV_MAP_FRONT. Las celdas de fuera de un mapa sin ZXV_MAP_WRAP no se dibujan. Una sola llamada puede cubrir hasta 1024 píxeles de ancho.
• zxv_map_cell devuelve la celda del píxel (px, py) del mapa (0 fuera de un mapa que no se repite).

Modo 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 dibuja n líneas desde la línea y del destino; la línea y + i usa l[i]. El píxel x de una línea enseña el texel (u + x·du, v + x·dv), con la parte entera de cada coordenada.
• zxv_m7_camera rellena l[0..n-1] para las líneas 0 a n−1 del destino: la línea i por debajo del horizonte está a la distancia altura × focal / (i − horizonte), con el centro del destino en la x de la cámara. Las líneas del horizonte para arriba quedan a cero. Se dibuja con zxv_m7_draw(t, l + y0, y0, n).

Ficheros de gráficos .gfx#

Declarado en zxv_gfxfile.h. Se compila con gfxfile.c. Las explicaciones, un ejemplo y el formato están en Gráficos.

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 da 1 si data es un .gfx entero y bien formado, y deja f listo; si no, 0. El fichero puede estar donde sea: leído con zxv_file_load o dentro del programa.
• Los objetos del fichero no van alineados, así que cada función copia el suyo en buf, alineado a 4. Da los bytes que necesita buf, o 0 si el objeto no está o no vale. Si buf es NULL o room es menor, no copia nada: así se pregunta el tamaño.
• zxv_gfxf_sprite: el sprite num como bitmap (b apunta a buf).
• zxv_gfxf_tiles: los tiles de lado size (8 o 16), seguidos. En *count, cuántos son (count puede ser NULL).
• zxv_gfxf_map: las celdas del mapa num, en buf. m queda con ellas y con tiles, los tiles de su lado (de zxv_gfxf_tiles).
• zxv_gfxf_texture: los texels de la textura num del modo 7.
• zxv_gfxf_screen: los píxeles de la pantalla num, como los de una página de la VRAM (24.576 bytes en el modo 0, 98.304 en el 1), y su modo y su borde en *mode y *border. buf puede ser la página que no se ve.
• zxv_gfxf_screen_palette: los 16 colores RGB565 de la pantalla num, para ponerlos en ZXV_PALETTE(t). Da 1 si la pantalla lleva paleta; si no, 0 y los colores de siempre.
• zxv_gfxf_find: los datos de un objeto tal como están en el fichero (sin alinear) y su longitud en *len, o NULL si no está.

Registros de vídeo#

Escríbelos cuando quieras; el sistema los aplica en el siguiente VBLANK.

Con scroll, el píxel (x, y) de la pantalla enseña el píxel ((x + SCROLL_X) mod ancho, (y + SCROLL_Y) mod alto) de la página.

Tamaños de página (ZXV_V_VSIZE, solo en el modo 0; en el modo 1 se ignora):

Tablas de remapeo: cuatro tablas de 16 bytes desde ZXV_REMAP_TABLES (la tabla t en ZXV_REMAP_TABLES + 16·t). La entrada v es el color que se ve para el valor de píxel v. Empiezan siendo la identidad.

Paletas: cada tabla tiene la suya, 16 colores RGB565 (u16) desde ZXV_PALETTE(t) (ZXV_PALETTES + 32·t, en 0x2000_0480). Un píxel de valor v en una línea que usa la tabla t se ve con el color paleta[t][tabla[t][v]]. Empiezan con los colores de siempre (ZXV_STD_RGB565), y la ROM los vuelve a poner al empezar cada programa. Como las tablas, se leen justo después de cada VBLANK.

Tabla por línea: en ZXV_LINE_TABLE, una entrada de ZXV_LINE_ENTRY_SIZE (8) bytes por línea del cuadro entero, borde incluido: 240 líneas en el modo 0 (la imagen empieza en la línea 24) y 480 en el modo 1 (la imagen, desde la línea 48): ZXV_FRAME_LINES(modo) y ZXV_BORDER_LINES(modo). El cuadro es de ZXV_FRAME_W × ZXV_FRAME_H (640 × 480), con un borde de ZXV_BORDER_X (64) píxeles a cada lado y ZXV_BORDER_Y (48) líneas arriba y abajo.

En las líneas del borde solo cuenta el campo del borde.

Cuándo es seguro cambiar las cosas: justo después de cada VBLANK el sistema lee la página visible, los registros y las tablas. Mientras el bit ZXV_SYSF_LINK_BUSY de ZXV_SV_SYSFLAGS valga 1 (hasta 1,5 ms en el modo 0 y 6 ms en el modo 1 o con una página grande), no escribas en la página visible ni en la tabla por línea.

Memoria de vídeo: ZXV_VRAM0_BASE (0x2000_4000) y ZXV_VRAM1_BASE (0x2001_C000), de ZXV_VRAM_PAGE_SIZE (96 KB) cada una.

Registros de entrada#

Códigos HID de las teclas más usadas: A–Z 0x04–0x1D; 1–9 0x1E–0x26, 0 0x27; Intro 0x28, Esc 0x29, Retroceso 0x2A, Tab 0x2B, Espacio 0x2C; F1–F12 0x3A–0x45; Insert 0x49, Inicio 0x4A, RePág 0x4B, Supr 0x4C, Fin 0x4D, AvPág 0x4E; derecha 0x4F, izquierda 0x50, abajo 0x51, arriba 0x52; Ctrl, Mayús y Alt izquierdas 0xE0–0xE2, las derechas 0xE4–0xE6. Identifican la posición de la tecla en un teclado de EE. UU.

La matriz del Spectrum (ZXV_I_KEYROWS[n], bits 0 a 4):

Mayús es CAPS SHIFT y Ctrl, SYMBOL SHIFT; Retroceso, Esc y los cursores pulsan sus combinaciones del Spectrum (CAPS SHIFT + 0, SPACE, 5–8), y los signos de puntuación pulsan SYMBOL SHIFT con la tecla que toca.

Registros de sonido#

Las colas son más fáciles de usar con zxv_ay_write, zxv_beeper_event y zxv_ay_event.

La mezcla estéreo: en ABC, izquierda = A + la mitad de B y derecha = C + la mitad de B; en ACB, izquierda = A + la mitad de C y derecha = B + la mitad de C; en mono, los tres en los dos lados. El beeper va a los dos lados. Los canales de la misma letra de los dos chips se suman.

Variables del sistema#

En ZXV_SYSVARS (0x2000_0700), de 32 bits cada una:

Códigos de error#

Si se saca la tarjeta, o deja de responder, con ficheros o carpetas abiertos, estos conservan su número (un fichero que se abra después no se queda con ninguno de ellos) y todas las llamadas sobre ellos dan ZXV_E_NOCARD o ZXV_E_IO hasta que los cierras. Cerrarlos da ZXV_OK: lo que ya se había escrito está en la tarjeta.

Números de las funciones de la API#

La API es una tabla de 256 direcciones de función en ZXV_API_TABLE (0x2000_0000). La entrada n está en ZXV_API_TABLE + 4·n. Desde C, las funciones de las cabeceras usan la macro ZXV_API_FN(n, tipo), que lee la entrada y la convierte en un puntero a función de ese tipo. En ensamblador:

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

zxv_lang_get y las funciones del ratón leen la memoria directamente y no tienen número. Las entradas sin usar devuelven −1. Como la tabla está en la RAM, un programa puede cambiar una entrada para interceptar una rutina.

Mapa de memoria#

Área de sistema:

El resto del área de sistema es para uso interno de la ROM.

El procesador es un RISC-V de 32 bits (RV32IMAC con las extensiones Zba, Zbb, Zbs, Zbkb y Zcb, -march=rv32imac_zicsr_zifencei_zba_zbb_zbs_zbkb_zcb -mabi=ilp32), con el byte bajo primero. Los accesos desalineados a datos de 16 o 32 bits detienen el programa. Los programas pueden activar y desactivar las interrupciones (el bit 3 de mstatus) y leer mcycle/minstret; los demás registros de control son del sistema.

Cómo coloca el SDK un programa#

zxv.ld pone, desde 0x2003_4000: el código (empezando por crt0.S), las constantes, las variables con valor inicial y luego las variables a cero (el BSS). Define estos símbolos:

La pila es la del sistema: empieza cerca de ZXV_URAM_END y crece hacia abajo.

El formato .zxv#

Una cabecera de 72 bytes, seguida de la pantalla de carga, si la hay, y de la imagen del programa, que se copia en la dirección de carga. Todos los números van con el byte bajo primero.

Al cargarlo, el sistema comprueba la firma, el tamaño de la cabecera, el perfil, que la dirección de carga esté alineada a 4 y el punto de entrada dentro de la imagen, que la imagen y el BSS quepan en la RAM de usuario dejando 4 KB por debajo de la pila del sistema, y el CRC. Después borra el BSS, pone el modo de vídeo (si la pantalla de carga no es ya de ese modo) y llama al punto de entrada como int entry(void). Un tope de pila distinto de 0 tiene que estar alineado a 16 y quedar entre el final del BSS y ZXV_URAM_END. Un .zxv con la cabecera de 64 bytes de antes no carga (ZXV_E_FORMAT): hay que volver a pasarlo por elf2zxv.py.

La pantalla de carga son los datos de un objeto pantalla de un .gfx:

ZXV_SCREEN_HEAD (4) es el tamaño de la cabecera de la pantalla y ZXV_SCREEN_SIZE_F(modo, marcas), el de la pantalla entera. La ROM la pone antes de cargar la imagen, con su modo, su borde y, si la trae, su paleta en la tabla 0. Si es del modo del programa, el programa empieza con ella en la página 0; si no, en su modo y con la pantalla borrada.

Herramientas#

elf2zxv.py#

python3 sdk/tools/elf2zxv.py ENTRADA.elf SALIDA.zxv [--name NOMBRE] [--mode 0|1] [--stack DIRECCIÓN] [--screen PANTALLA]

Comprueba que el programa está dentro de la RAM de usuario y escribe la dirección de carga, el punto de entrada y los tamaños. Como png2gfx.py, habla en español si tu sistema está en español, y si no, en inglés.

png2gfx.py#

python3 sdk/tools/png2gfx.py SALIDA.gfx ORDEN...
python3 sdk/tools/png2gfx.py --list FICHERO.gfx

Las órdenes están en Gráficos, junto con el formato .gfx. Los números de sprite van del 0 al 255, los de tile del 0 al 4095, los de mapa del 0 al 15 y los de textura del 0 al 3, como en el BASIC, y los de pantalla del 0 al 255. Lee cualquier PNG menos los entrelazados, sin otros paquetes de Python.

La biblioteca estándar de C (picolibc)#

Los programas compilados con picolibc y zxvc.c (ver la guía) pueden usar:

• Los errores de la API llegan en errno (ENOENT, EEXIST, ENOTEMPTY, ENOSPC...; sin tarjeta, ENODEV).
• Los descriptores 0, 1 y 2 son la consola; los de los ficheros empiezan en el 3.
• struct dirent tiene d_name, d_type (DT_DIR o DT_REG) y, de más, el tamaño en d_size.
• printf con decimales ocupa unos 7 KB más; con -DPICOLIBC_INTEGER_PRINTF_SCANF al enlazar se usa el pequeño, solo de enteros.
• La consola habla UTF-8, como las cadenas de C: printf("¿Qué tal?") enseña las tildes, y fgets da en UTF-8 lo que se teclea (la ñ son dos bytes). Las letras que no tiene la fuente de la ROM salen como ?.

Definiciones internas#

zxv.h es compartido con la ROM y el emulador, así que define también cosas que los programas no deben usar: la interfaz de la plataforma (ZXV_PLATFORM_IF y todas las ZXV_PIF_...), el buzón del depurador del BASIC (ZXV_DBG_BOX y todas las ZXV_DBG...), el espacio de trabajo de la ROM (ZXV_ROM_WORKSPACE, ZXV_ROM_WORKSPACE_END), las direcciones de la flash (ZXV_FLASH_BASE, ZXV_FLASH_SIZE, ZXV_PLATFORM_BASE, ZXV_ROM_SIZE) y las de la SRAM (ZXV_SRAM_BASE, ZXV_SRAM_SIZE, ZXV_RESERVED_END). Están aquí solo para que las reconozcas.