retrograph 0.2.1

data/src/retrograph.c

@@ -0,0 +1,695 @@
+/* retrograph
+ * 
+ * Copyright (c) 2009  MenTaLguY <mental@rydia.net>
+ * 
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ * 
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+#include "retrograph.h"
+#include <string.h>
+
+#define MAX_SPRITES 64
+#define MAX_SPRITES_PER_SCANLINE 8
+
+typedef enum {
+    TEXT_A=0,
+    TEXT_B=1,
+    GRAPHICS_A=2,
+    GRAPHICS_B=3
+} vdu_mode_t;
+
+static inline int is_graphics_mode(vdu_mode_t mode) {
+    return mode >> 1;
+}
+
+static inline uint8_t SPRITE_ATTRS_TO_GENERIC(uint8_t attrs) {
+    return attrs << 1;
+}
+static inline uint8_t BG_ATTRS_TO_GENERIC(uint8_t attrs) {
+    return (attrs & 0x0f) | ((attrs << 1) & 0xe0);
+}
+
+#define ROW_BYTES (RETROGRAPH_DISPLAY_WIDTH * RETROGRAPH_BYTES_PER_PIXEL)
+#define TEXT_PATTERN_STRIDE 8
+#define GRAPHICS_A_PATTERN_STRIDE 16
+#define GRAPHICS_B_PATTERN_STRIDE 32
+
+#define TILE_VFLIP_BIT 13
+#define TILE_VFLIP_MASK (1 << TILE_VFLIP_BIT)
+#define TILE_HFLIP_BIT 14
+#define TILE_HFLIP_MASK (1 << TILE_HFLIP_BIT)
+
+#define PRIORITY_BIT 15
+#define PRIORITY_MASK (1 << PRIORITY_BIT)
+
+#define ENABLE_SPRITES_BIT 3
+#define ENABLE_BG_BIT 2
+
+#define TILE_COLOR_SHIFT 9
+#define TILE_COLOR_MASK 0x0e00
+#define TILE_COLOR_LOSS 2
+#define TILE_COLOR_HI_BIT (TILE_COLOR_SHIFT+2)
+#define TILE_COLOR_HI_MASK (1 << TILE_COLOR_HI_BIT)
+#define TILE_PATTERN_SHIFT 0
+#define TILE_PATTERN_MASK 0x1ff
+#define TILE_PATTERN_HI_BIT 8
+#define TILE_PATTERN_HI_MASK (1 << TILE_PATTERN_HI_BIT)
+#define SPRITE_VDOUBLE_BIT 11
+#define SPRITE_VDOUBLE_MASK (1 << SPRITE_VDOUBLE_BIT)
+#define SPRITE_HDOUBLE_BIT 12
+#define SPRITE_HDOUBLE_MASK (1 << SPRITE_HDOUBLE_BIT)
+
+struct retrograph_vdu_tag {
+    retrograph_error_t error;
+    unsigned refcount;
+
+    uint8_t vram[16384];
+    uint8_t sprites[256];
+    uint8_t palette[32];
+    char enable_bg;
+    char enable_sprites;
+    vdu_mode_t mode;
+    retrograph_addr_t text_pattern_base;
+    retrograph_addr_t bg_pattern_base;
+    retrograph_addr_t name_base;
+    uint8_t bg_scroll_x;
+    uint8_t bg_scroll_y;
+
+    unsigned current_scanline;
+    uint32_t palette_cache[32];
+    /* +16 to accomodate double-width sprites */
+    uint32_t row_buffer[RETROGRAPH_DISPLAY_WIDTH + 16];
+};
+
+static retrograph_error_t no_memory_error = RETROGRAPH_NO_MEMORY;
+#define NO_MEMORY_SINGLETON ((retrograph_vdu_t)&no_memory_error);
+static inline int is_singleton_vdu(struct retrograph_vdu_tag const *vdu) {
+    return vdu == NO_MEMORY_SINGLETON;
+}
+
+static inline retrograph_addr_t decode_text_pattern_base(uint8_t base) {
+    return (base & 0x30) << 8;
+}
+
+static inline retrograph_addr_t decode_bg_pattern_base(uint8_t base) {
+    return (base & 0x20) << 8;
+}
+
+static inline retrograph_addr_t decode_name_base(uint8_t base) {
+    return ((base & 0x30) | 0x08) << 8;
+}
+
+static inline retrograph_addr_t compute_sprite_pattern_base(
+    retrograph_addr_t bg_pattern_base
+) {
+    return 0x2000 - bg_pattern_base;
+}
+
+retrograph_vdu_t retrograph_new() {
+    retrograph_vdu_t vdu = (retrograph_vdu_t)malloc(sizeof(struct retrograph_vdu_tag));
+    if (vdu) {
+        vdu->error = RETROGRAPH_OK;
+        vdu->refcount = 1;
+        memset(&vdu->vram, 0, sizeof(vdu->vram));
+        memset(&vdu->sprites, 0, sizeof(vdu->sprites));
+        memset(&vdu->palette, 0, sizeof(vdu->palette));
+        vdu->enable_bg = 0;
+        vdu->enable_sprites = 0;
+        vdu->mode = TEXT_A;
+        vdu->text_pattern_base = decode_text_pattern_base(0);
+        vdu->bg_pattern_base = decode_bg_pattern_base(0);
+        vdu->name_base = decode_name_base(0);
+        vdu->bg_scroll_x = 0;
+        vdu->bg_scroll_y = 0;
+        vdu->current_scanline = RETROGRAPH_DISPLAY_HEIGHT;
+    } else {
+        vdu = NO_MEMORY_SINGLETON;
+    }
+    return vdu;
+}
+
+void retrograph_ref(retrograph_vdu_t vdu) {
+    if (vdu && !is_singleton_vdu(vdu)) {
+        vdu->refcount++;
+    }
+}
+
+void retrograph_destroy(retrograph_vdu_t vdu) {
+    if (vdu && !is_singleton_vdu(vdu) && !--vdu->refcount) {
+        free(vdu);
+    }
+}
+
+retrograph_error_t retrograph_get_error(retrograph_vdu_t vdu) {
+    if (vdu) {
+        retrograph_error_t const error = vdu->error;
+        if (!is_singleton_vdu(vdu)) {
+            vdu->error = RETROGRAPH_OK;
+        }
+        return error;
+    } else {
+        return RETROGRAPH_INVALID_ARGUMENT;
+    }
+}
+
+static void write_vram(retrograph_vdu_t vdu, retrograph_addr_t offset, uint8_t const *bytes, retrograph_addr_t n_bytes) {
+    memcpy(vdu->vram + offset, bytes, n_bytes);
+}
+
+static void write_sprites(retrograph_vdu_t vdu, retrograph_addr_t offset, uint8_t const *bytes, retrograph_addr_t n_bytes) {
+    memcpy(vdu->sprites + offset, bytes, n_bytes);
+}
+
+static void write_palette(retrograph_vdu_t vdu, retrograph_addr_t offset, uint8_t const *bytes, retrograph_addr_t n_bytes) {
+    memcpy(vdu->palette + offset, bytes, n_bytes);
+}
+
+static void write_unmapped(retrograph_vdu_t vdu, retrograph_addr_t offset, uint8_t const *bytes, retrograph_addr_t n_bytes) {
+}
+
+static void write_registers(retrograph_vdu_t vdu, retrograph_addr_t offset, uint8_t const *bytes, retrograph_addr_t n_bytes) {
+    for (; n_bytes > 0; n_bytes--, offset++, bytes++) {
+        switch (offset) {
+        case 0:
+            vdu->enable_sprites = (*bytes >> ENABLE_SPRITES_BIT) & 1;
+            vdu->enable_bg = (*bytes >> ENABLE_BG_BIT) & 1;
+            vdu->mode = (vdu_mode_t)(*bytes & 3);
+            break;
+        case 1:
+            vdu->text_pattern_base = decode_text_pattern_base(*bytes);
+            vdu->bg_pattern_base = decode_bg_pattern_base(*bytes);
+            break;
+        case 2:
+            vdu->name_base = decode_name_base(*bytes);
+            break;
+        case 4:
+            vdu->bg_scroll_x = *bytes;
+            break;
+        case 5:
+            vdu->bg_scroll_y = *bytes;
+            break;
+        }
+    }
+}
+
+typedef void (*write_func_t)(retrograph_vdu_t vdu, retrograph_addr_t offset, uint8_t const *bytes, retrograph_addr_t n_bytes);
+
+typedef struct mem_region_tag {
+    retrograph_addr_t start_address;
+    write_func_t write_func;
+} mem_region_t;
+
+static mem_region_t const mem_regions[] = {
+    { 0x0000, write_vram },
+    { 0x4000, write_vram },
+    { 0x7e00, write_sprites },
+    { 0x7f00, write_palette },
+    { 0x7f20, write_unmapped },
+    { 0x7ff8, write_registers },
+    { 0x8000, NULL }
+};
+
+void retrograph_write(retrograph_vdu_t vdu, retrograph_addr_t start_address,
+                      void const *data, size_t n_bytes)
+{
+    size_t start;
+    uint8_t const *bytes = (uint8_t const *)data;
+
+    if (!vdu || vdu->error) {
+        return;
+    }
+
+    if (n_bytes < 0) {
+        vdu->error = RETROGRAPH_INVALID_ARGUMENT;
+        return;
+    }
+
+    start = start_address;
+    while (n_bytes > 0) {
+        mem_region_t const *region = mem_regions;
+        size_t end;
+        size_t length;
+        start &= 0x7fff;
+        while (start >= (size_t)(region+1)->start_address) {
+            region++;
+        }
+        end = start + n_bytes;
+        if (end >= (size_t)(region+1)->start_address) {
+            end = (region+1)->start_address;
+        }
+        length = end - start;
+        region->write_func(vdu,
+                           (retrograph_addr_t)start - region->start_address,
+                           bytes, (retrograph_addr_t)length);
+        n_bytes -= length;
+        bytes += length;
+        start += length;
+    }
+}
+
+static void update_palette_cache(retrograph_vdu_t vdu) {
+    int i;
+    for (i = 0; i < 32; i++) {
+        uint8_t entry;
+        uint8_t r, g, b;
+        entry = vdu->palette[i];
+        r = (entry & 0x30) << 2;
+        r |= r >> 2;
+        r |= r >> 4;
+        g = (entry & 0x0c) << 4;
+        g |= g >> 2;
+        g |= g >> 4;
+        b = (entry & 0x03) << 6;
+        b |= b >> 2;
+        b |= b >> 4;
+        vdu->palette_cache[i] = (r << RETROGRAPH_RED_SHIFT) |
+                                (g << RETROGRAPH_GREEN_SHIFT) |
+                                (b << RETROGRAPH_BLUE_SHIFT);
+    }
+}
+
+static void clear_row_buffer(uint32_t * const out_buffer, uint32_t const color) {
+    int i;
+    for (i = 0; i < RETROGRAPH_DISPLAY_WIDTH; i++) {
+        out_buffer[i] = color;
+    }
+}
+
+#define DEFINE_RENDER_CHAR(width) \
+static inline void render_char ## width(uint32_t * const out_buffer, \
+                                        uint8_t const c, \
+                                        uint8_t const attrs, \
+                                        uint8_t const * const patterns, \
+                                        uint32_t const * const palette) \
+{ \
+    uint8_t pattern_row; \
+    uint32_t colors[2]; \
+    int i; \
+    colors[1] = palette[attrs % 16]; \
+    colors[0] = palette[attrs / 16]; \
+    pattern_row = patterns[c * TEXT_PATTERN_STRIDE]; \
+    for (i = 0; i < width; i++) { \
+        out_buffer[i] = colors[pattern_row & 1]; \
+        pattern_row >>= 1; \
+    } \
+}
+
+DEFINE_RENDER_CHAR(6)
+DEFINE_RENDER_CHAR(8)
+
+static void render_line_text_a(uint32_t *out_buffer, uint8_t const *names,
+                               uint8_t y_fine, uint8_t const *patterns,
+                               uint32_t const *palette, char enable_bg)
+{
+    int i;
+
+    if (enable_bg) {
+        patterns += y_fine;
+
+        /* 8px padding on either side of display */
+        out_buffer += 8;
+
+        /* draw text columns */
+        for (i = 0; i < 40; i++) {
+            render_char6(out_buffer, names[0], names[1], patterns, palette);
+            out_buffer += 6;
+            names += 2;
+        }
+    }
+}
+
+static void render_line_text_b(uint32_t *out_buffer, uint8_t const *names,
+                               uint8_t y_fine, uint8_t const *patterns,
+                               uint32_t const *palette, char enable_bg)
+{
+    int i;
+    if (enable_bg) {
+        patterns += y_fine;
+        for (i = 0; i < 32; i++) {
+            render_char8(out_buffer, names[0], names[1], patterns, palette);
+            out_buffer += 8;
+            names += 2;
+        }
+    }
+}
+
+static inline uint16_t unpack_uint16(uint8_t const * const bytes) {
+    return (uint16_t)((bytes[1] << 8) | bytes[0]);
+}
+
+static inline uint32_t unpack_uint32(uint8_t const * const bytes) {
+    return (uint32_t)((bytes[3] << 24) | (bytes[2] << 16) | (bytes[1] << 8) | bytes[0]);
+}
+
+#define RENDER_SINGLE_PIXEL out_buffer[i] = palette[color | base_color]
+#define RENDER_DOUBLE_PIXEL out_buffer[i*2] = palette[color | base_color]; \
+                            out_buffer[i*2+1] = palette[color | base_color]
+
+#define DEFINE_RENDER_TILE(bpp, suffix, RENDER_PIXEL, row_type, unpack_row) \
+static inline void render_ ## suffix ## bpp(uint32_t *out_buffer, \
+                                            uint16_t cell, \
+                                            uint8_t const *vflip_patterns[2], \
+                                            uint32_t const *palette) \
+{ \
+    row_type pattern_row; \
+    uint8_t base_color; \
+    int i; \
+    { \
+        uint8_t const *pattern_ptr; \
+        pattern_ptr = vflip_patterns[(cell >> TILE_VFLIP_BIT) & 1] + \
+                      ((cell & TILE_PATTERN_MASK) >> TILE_PATTERN_SHIFT) * \
+                      bpp * 8; \
+        pattern_row = unpack_row(pattern_ptr); \
+    } \
+    base_color = (uint8_t)((cell & TILE_COLOR_MASK) >> \
+                           (TILE_COLOR_SHIFT - TILE_COLOR_LOSS)); \
+    if (cell & TILE_HFLIP_MASK) { \
+        for (i = 0; i < 8; i++) { \
+            uint8_t color; \
+            color = (uint8_t)(pattern_row >> ((8 * bpp) - bpp)); \
+            if (color) { \
+                RENDER_PIXEL; \
+            } \
+            pattern_row <<= bpp; \
+        } \
+    } else { /* no hflip */ \
+        for (i = 0; i < 8; i++) { \
+            uint8_t color; \
+            color = (uint8_t)(pattern_row & ((1 << bpp) - 1)); \
+            if (color) { \
+                RENDER_PIXEL; \
+            } \
+            pattern_row >>= bpp; \
+        } \
+    } \
+}
+
+DEFINE_RENDER_TILE(2, tile, RENDER_SINGLE_PIXEL, uint16_t, unpack_uint16)
+DEFINE_RENDER_TILE(2, tile_double, RENDER_DOUBLE_PIXEL, uint16_t, unpack_uint16)
+DEFINE_RENDER_TILE(4, tile, RENDER_SINGLE_PIXEL, uint32_t, unpack_uint32)
+DEFINE_RENDER_TILE(4, tile_double, RENDER_DOUBLE_PIXEL, uint32_t, unpack_uint32)
+
+#define DEFINE_RENDER_BG_LINE(bpp) \
+static void render_bg_line ## bpp(uint32_t *out_buffer, \
+                                  uint8_t x_coarse, uint8_t x_fine, \
+                                  uint8_t const *names, \
+                                  uint8_t const *vflip_patterns[2], \
+                                  uint16_t toggle_bits, \
+                                  uint32_t const *palette) \
+{ \
+    int i; \
+    uint8_t const *name_cursor; \
+    out_buffer += (8 - x_fine) % 8; \
+    x_coarse = (x_coarse + (x_fine != 0)) % 32; \
+    name_cursor = names + x_coarse * 2; \
+    /* render up to the end of the nametable row */ \
+    for (i = x_coarse; i < 32; i++) { \
+        uint16_t cell; \
+        cell = (uint16_t)name_cursor[0] | \
+               ((uint16_t)BG_ATTRS_TO_GENERIC(name_cursor[1]) << 8); \
+        cell ^= toggle_bits; \
+        if (!(cell & PRIORITY_MASK)) { \
+            render_tile ## bpp(out_buffer, cell, vflip_patterns, palette); \
+        } \
+        out_buffer += 8; \
+        name_cursor += 2; \
+    } \
+    /* render remainder of line from beginning of nametable row */ \
+    name_cursor = names; \
+    for (i = 0; i < x_coarse; i++) { \
+        uint16_t cell; \
+        cell = unpack_uint16(name_cursor) ^ toggle_bits; \
+        if (!(cell & PRIORITY_MASK)) { \
+            render_tile ## bpp(out_buffer, cell, vflip_patterns, palette); \
+        } \
+        out_buffer += 8; \
+        name_cursor += 2; \
+    } \
+}
+
+DEFINE_RENDER_BG_LINE(2)
+DEFINE_RENDER_BG_LINE(4)
+
+/* result is in sprite rows rather than display rows */
+static inline unsigned compute_sprite_line(uint8_t row, uint8_t const *sprite) {
+    unsigned sprite_line;
+    /* sprite_y = sprite[1] - 1 */
+    sprite_line = row - (unsigned)sprite[1] + 1;
+    /* vertical doubling */
+    sprite_line >>= (SPRITE_ATTRS_TO_GENERIC(sprite[3]) &
+                     (SPRITE_VDOUBLE_MASK >> 8)) >>
+                    (SPRITE_VDOUBLE_BIT - 8);
+    return sprite_line;
+}
+
+static void render_sprites_line(uint32_t *out_buffer, uint8_t row,
+                                uint8_t const *sprites,
+                                uint8_t const *patterns,
+                                uint32_t const *palette)
+{
+    unsigned sprite_lines[MAX_SPRITES];
+    int i, n_sprites;
+    /* find the first MAX_SPRITES_PER_SCANLINE sprites spanning this line */
+    for (i = 0, n_sprites = 0;
+         i < MAX_SPRITES && n_sprites < MAX_SPRITES_PER_SCANLINE;
+         i++)
+    {
+        unsigned sprite_line;
+        /* takes double-height sprites into account */
+        sprite_line = compute_sprite_line(row, &sprites[i*4]);
+        /* row >= sprite_y && row < sprite_y + sprite_height */
+        if (sprite_line < 8) {
+            n_sprites++;
+        }
+        sprite_lines[i] = sprite_line;
+    }
+    /* work backwards, rendering sprites on this line as we encounter them */
+    for (i--; i >= 0; i--) {
+        uint8_t const * const sprite = &sprites[i*4];
+        unsigned sprite_line;
+        sprite_line = sprite_lines[i];
+        if (sprite_line < 8) {
+            uint16_t cell;
+            uint8_t sprite_x;
+            uint8_t const *vflip_patterns[2];
+            uint16_t render_cell;
+            cell = (uint16_t)sprite[2] |
+                   ((uint16_t)SPRITE_ATTRS_TO_GENERIC(sprite[3]) << 8);
+            vflip_patterns[0] = patterns + 4 * sprite_line;
+            vflip_patterns[1] = patterns + 4 * (7 - sprite_line);
+            sprite_x = sprite[0];
+            render_cell = cell;
+            render_cell &= TILE_HFLIP_MASK | TILE_VFLIP_MASK |
+                           (TILE_COLOR_MASK ^ TILE_COLOR_HI_MASK) |
+                           (TILE_PATTERN_MASK ^ TILE_PATTERN_HI_MASK);
+            render_cell |= TILE_COLOR_HI_MASK;
+            if (cell & SPRITE_HDOUBLE_MASK) {
+                render_tile_double4(&out_buffer[sprite_x], render_cell,
+                                    vflip_patterns, palette);
+            } else {
+                render_tile4(&out_buffer[sprite_x], render_cell,
+                             vflip_patterns, palette);
+            }
+        }
+    }
+}
+
+static void render_line_graphics_a(uint32_t *out_buffer,
+                                   uint8_t const * const names,
+                                   uint8_t x_coarse, uint8_t x_fine,
+                                   uint8_t y_fine, uint8_t row,
+                                   uint8_t const *patterns,
+                                   retrograph_addr_t pattern_base,
+                                   uint8_t const *sprites,
+                                   uint32_t const *palette,
+                                   char enable_bg, char enable_sprites)
+{
+    uint8_t const *vflip_patterns[2];
+
+    vflip_patterns[0] = patterns + pattern_base + y_fine * 2;
+    vflip_patterns[1] = patterns + pattern_base + (7 - y_fine) * 2;
+
+    if (enable_bg) {
+        render_bg_line2(out_buffer, x_coarse, x_fine, names,
+                        vflip_patterns, 0, palette);
+    }
+    if (enable_sprites) {
+        uint8_t const *sprite_patterns;
+        sprite_patterns = patterns + compute_sprite_pattern_base(pattern_base);
+        render_sprites_line(out_buffer, row, sprites, sprite_patterns,
+                            palette);
+    }
+    if (enable_bg) {
+        render_bg_line2(out_buffer, x_coarse, x_fine, names,
+                        vflip_patterns, PRIORITY_MASK, palette);
+    }
+}
+
+static void render_line_graphics_b(uint32_t *out_buffer, uint8_t const *names,
+                                   uint8_t x_coarse, uint8_t x_fine,
+                                   uint8_t y_fine, uint8_t row,
+                                   uint8_t const *patterns,
+                                   retrograph_addr_t pattern_base,
+                                   uint8_t const *sprites,
+                                   uint32_t const *palette,
+                                   char enable_bg, char enable_sprites)
+{
+    uint8_t const *vflip_patterns[2];
+    uint16_t hi_index;
+
+    hi_index = (pattern_base != 0) << 9;
+    vflip_patterns[0] = patterns + y_fine * 4;
+    vflip_patterns[1] = patterns + (7 - y_fine) * 4;
+
+    if (enable_bg) {
+        render_bg_line4(out_buffer, x_coarse, x_fine, names,
+                        vflip_patterns, hi_index, palette);
+    }
+    if (enable_sprites) {
+        uint8_t const *sprite_patterns;
+        sprite_patterns = patterns + compute_sprite_pattern_base(pattern_base);
+        render_sprites_line(out_buffer, row, sprites, sprite_patterns,
+                            palette);
+    }
+    if (enable_bg) {
+        render_bg_line4(out_buffer, x_coarse, x_fine, names,
+                        vflip_patterns, PRIORITY_MASK | hi_index, palette);
+    }
+}
+
+static void render_line(retrograph_vdu_t vdu, unsigned scanline, uint8_t *dest)
+{
+    uint8_t const *name_row;
+    uint8_t bg_x_coarse;
+    uint8_t bg_x_fine;
+    uint8_t bg_y_coarse;
+    uint8_t bg_y_fine;
+
+    { /* scrolling */
+        unsigned bg_y;
+       
+        if (is_graphics_mode(vdu->mode)) {
+            bg_y = scanline + vdu->bg_scroll_y;
+        } else {
+            /* text modes scroll vertically in full-character increments */
+            bg_y = scanline + (vdu->bg_scroll_y & ~7);
+            if (vdu->mode == TEXT_A) {
+                bg_y -= 12;
+            }
+        }
+
+        if (is_graphics_mode(vdu->mode)) {
+            bg_x_coarse = vdu->bg_scroll_x / 8;
+            bg_x_fine = vdu->bg_scroll_x % 8;
+        } else {
+            /* text modes have no horizontal scrolling */
+            bg_x_coarse = 0;
+            bg_x_fine = 0;
+        }
+
+        bg_y_coarse = (uint8_t)(bg_y / 8);
+        switch (vdu->mode) {
+        case TEXT_A:
+            bg_y_coarse %= 25;
+            break;
+        case TEXT_B:
+            bg_y_coarse %= 28;
+            break;
+        default:
+            bg_y_coarse %= 32;
+        }
+        bg_y_fine = (uint8_t)(bg_y % 8);
+    }
+
+    update_palette_cache(vdu);
+
+    switch (vdu->mode) {
+    case TEXT_A:
+        /* stride is 40 2-byte cells */
+        name_row = vdu->vram + vdu->name_base + bg_y_coarse * (40 * 2);
+        break;
+    default:
+        /* stride is 32 2-byte cells */
+        name_row = vdu->vram + vdu->name_base + bg_y_coarse * (32 * 2);
+    }
+
+    clear_row_buffer(vdu->row_buffer, vdu->palette_cache[0]);
+    switch (vdu->mode) {
+    case TEXT_A:
+        /* 12px padding above and below display */
+        if (scanline >= 12 ||
+            scanline < RETROGRAPH_DISPLAY_HEIGHT - 12)
+        {
+            render_line_text_a(vdu->row_buffer, name_row, bg_y_fine,
+                               vdu->vram + vdu->text_pattern_base,
+                               vdu->palette_cache, vdu->enable_bg);
+        }
+        break;
+    case TEXT_B:
+        render_line_text_b(vdu->row_buffer, name_row, bg_y_fine,
+                           vdu->vram + vdu->text_pattern_base,
+                           vdu->palette_cache, vdu->enable_bg);
+        break;
+    case GRAPHICS_A:
+        render_line_graphics_a(vdu->row_buffer, name_row,
+                               bg_x_coarse, bg_x_fine, bg_y_fine,
+                               scanline, vdu->vram,
+                               vdu->bg_pattern_base,
+                               vdu->sprites,
+                               vdu->palette_cache,
+                               vdu->enable_bg, vdu->enable_sprites);
+        break;
+    case GRAPHICS_B:
+        render_line_graphics_b(vdu->row_buffer, name_row,
+                               bg_x_coarse, bg_x_fine, bg_y_fine,
+                               scanline, vdu->vram,
+                               vdu->bg_pattern_base,
+                               vdu->sprites,
+                               vdu->palette_cache,
+                               vdu->enable_bg, vdu->enable_sprites);
+        break;
+    }
+    memcpy(dest, vdu->row_buffer, ROW_BYTES);
+}
+
+void retrograph_begin_frame(retrograph_vdu_t vdu) {
+    if (!vdu || vdu->error) {
+        return;
+    }
+    vdu->current_scanline = 0;
+}
+
+void retrograph_render_scanline(retrograph_vdu_t vdu, void *dest,
+                                size_t dest_size)
+{
+    if (!vdu || vdu->error) {
+        return;
+    }
+    if (dest_size < ROW_BYTES) {
+        return;
+    }
+
+    if (vdu->current_scanline < RETROGRAPH_DISPLAY_HEIGHT) {
+        render_line(vdu, vdu->current_scanline, (uint8_t *)dest);
+        vdu->current_scanline++;
+    } else {
+        update_palette_cache(vdu);
+        clear_row_buffer(vdu->row_buffer, vdu->palette_cache[0]);
+        memcpy(dest, vdu->row_buffer, ROW_BYTES);
+    }
+}