This was not an engineering exercise. I have no real background in electronics. What I had was a broken board, enough tools, and a process that I believed could work.

Step 1: Strip the Board

The original board was badly oxidized. I suspect this was the result of both battery leakage and moisture exposure. The damage was severe, and although I cannot say for certain that none of the components were usable, that felt like a fair assumption.

Desoldering oxidized joints turned out to be more difficult than I expected. The oxide layer blocked heat, so the solder would not melt. After trying several approaches, I found the most reliable method was to cut the joint from underneath, exposing clean solder. Once that was exposed, I could melt it and use a desoldering gun to remove the component. It was a slow process, and it took patience.

In the end, I was left with a bare board. The components were gone, but the layout was still visible.

Step 2: Scan the Board

Fortunately, the Partner board has only two layers. I scanned both sides at high resolution. The scans gave me a clear reference for every trace, pad, and via. That was enough to begin recreating the design.

Step 3: Redraw in KiCad

I used KiCad to build a new version of the board. To identify and place the vias, I created a tool specifically for this task. It used older AI technologies such as vector spaces and similarity measures. I have written about that process elsewhere.

Once the vias were in place, I manually added all the components and drew every trace on both layers. It was time-consuming but straightforward. I was not working from a schematic or simulation. I was just copying what I saw in the scan.

Step 4: Validate the Layout

To make sure the KiCad layout matched the original design, I needed a second source of information. I had access to the original schematics, but they were not entirely reliable. Some were poorly scanned, and others contained mistakes. I could not depend on them completely.

Still, they were useful for cross-checking. My friend Sašo and I transcribed all the network connections from the schematics into a text file. I also wrote a Python program to extract the network data from the KiCad layout using a flood fill algorithm.

I then compared the two sets of data. Whenever there was a mismatch, it was usually obvious whether the problem was in the schematic or in my layout. I fixed the layout or adjusted the network list until both matched exactly.

That process took longer than expected, but once it was complete, I was confident that the recreated layout was accurate.

Step 5: Manufacture the Board

With validation complete, I exported the board as Gerber files and sent them to PCBWay.

The boards came back looking perfect. The fabrication quality was excellent. It was the first time in the project where I felt like something solid had been created.

Step 6: Assembly

I assembled the board using components from several sources. Most came from Mouser. A few came from stores here in Slovenia. Some I bought on eBay. Others were donated by members of the local retro computing community.

The process of soldering everything into place was uneventful. The board was well laid out, and with the components correctly sourced, there was nothing unusual.

Step 7: Switching It On

The board worked on the first try.

That outcome might sound simple, but it was the result of many careful steps. The work had not been fast or elegant. But it had been systematic, and each stage had been checked before moving on. So when the moment came to power it up, it worked.

Why I Did It

This was not a technical achievement. I started the project without knowing much about electronics, and I finished it in roughly the same state. But that was never the point.

I wanted to see if it was possible to rebuild the board by treating the damaged original as a kind of visual map. I trusted the process and was willing to do the manual work. That turned out to be enough.

There are many ways to experience retro computing. Most are easier than this. But this approach created something unusual. It was not an attempt to learn the system. It was just a decision to rebuild it, step by step, without skipping anything. And it worked.

Resources

• Project GitHub repository
• Project Read-Me

Read Also

• How AI Helped Us Recreate the IDP Motherboard

For the Benefit of Mr. Kite

As of SDCC 4.2.0+, the Z80 ABI (Application Binary Interface) has changed. The new calling convention improves performance by passing the first few function arguments in registers rather than on the stack, significantly reducing overhead in small or frequently called functions.

I discovered this the hard way when I recompiled my old Iskra Delta Partner code with SDCC 4.2.0+, only to find that everything broke — silently. The new ABI is now the default, and it’s not backward compatible with the previous stack-only model. I was both impressed by the optimization and frustrated by the fallout. My entire codebase — Z80 assembly wrappers, graphics drivers, and system libraries — suddenly needed revision.

I want to fully adopt the optimized ABI, so I started reviewing how arguments are passed by reading the documentation and compiling test cases. This article summarizes that information in a clearer, example-driven form — for the benefit of all fellow SDCC ABI martyrs now facing the same migration pain.

ABI overview

In the new Z80 calling convention, SDCC passes up to two arguments in registers. This table explains the basic rules of how SDCC passes function arguments under the default ABI introduced in SDCC 4.2.0 and later.

Notes:

• For 8-bit arguments, only the low byte of the 16-bit register is used (A, L).
• Additional arguments are passed right to left on the stack.
• Structs and pointers follow the same rules based on size.

Function argument examples

The following table shows how SDCC passes function arguments under the new default ABI. Function names are abbreviated:

• b = 8-bit (uint8_t)
• w = 16-bit (uint16_t)
• fn2b1w means: function takes 2 bytes, then 1 word

Each function is named according to its signature:

• fn1b — function accepts 1 byte (8 bit) argument
• fn2w — function accepts 2 word (16 bit) arguments
• fn1w1b — function accepts 1 word followed by 1 byte arguments

Here is the mapping table:

fn1b

void fn1b(uint8_t a);

Passing:

• a → A

fn1w

void fn1w(uint16_t a);

Passing:

• a → HL

fn2b

void fn2b(uint8_t a, uint8_t b);

Passing:

• a → A
• b → L

fn2w

void fn2w(uint16_t a, uint16_t b);

Passing:

• a → HL
• b → DE

fn1b1w

void fn1b1w(uint8_t a, uint16_t b);

Passing:

• a → L
• b → DE

Note: SDCC avoids using A when mixing 8-bit and 16-bit args. It uses L instead.

fn1w1b

void fn1w1b(uint16_t a, uint8_t b);

Passing:

• a → HL
• b → E

fn3b

void fn3b(uint8_t a, uint8_t b, uint8_t c);

Passing:

• a → A
• b → L
• c → stack

fn2b1w

void fn2b1w(uint8_t a, uint8_t b, uint16_t c);

Passing:

• a → A
• b → L
• c → stack (pushed right-to-left)

fn3w

void fn3w(uint16_t a, uint16_t b, uint16_t c);

Passing:

• a → HL
• b → DE
• c → stack

fn5b

void fn5b(uint8_t a, uint8_t b, uint8_t c, uint8_t d, uint8_t e);

Passing:

• a → A
• b → L
• c, d, e → stack

SDCC uses push af + inc sp to simulate push a (Z80 has no push a).

Return Values

Unlike the calling convention for function arguments, the ABI for return values has not changed in SDCC 4.2.0+. Return values have always been returned using registers, and the convention remains consistent:

• 8-bit values are returned in the L register (low byte of HL)
• 16-bit values are returned in the HL register
• 32-bit values (e.g. long, float) are returned across HL:DE with HL holding the high word and DE the low word

This applies uniformly to both the old and the new ABI.

Notes on push af trick

SDCC can push 8 bit value on the stack. But since Z80 has no push a, SDCC may emit:

push af     ; pushes A and F
inc sp      ; discard F, simulate push A

This ensures consistent behavior when passing extra 8-bit arguments on the stack.

Conclusion

The SDCC Z80 calling convention is now more efficient and modern:

• Arguments passed via registers (A/L/E or HL/DE)
• Reduced stack usage
• Compatible with inlined or __naked functions (if ABI respected)
• Stack is used only when arguments exceed available registers

Introduction

Haiku OS is an open-source successor to BeOS. If we had to describe it in one word, it would be charming. If you've ever wanted to write a program for this niche and enthusiast-driven retro operating system but were intimidated by cross-compilers, debuggers, and other complexities, this guide is for you.

Here, I will show you how to bypass much of that complexity and compile programs for Haiku from the comfort of your VSCode setup while debugging them on a Haiku VM.

First Set Up Haiku OS

Download the latest Haiku OS here and install it.

I am running Haiku OS Release 1 Beta 5 (64-bit) on VirtualBox on Linux, so I will describe that installation scenario. However, apart from VirtualBox-specific steps, the procedure is the same for any environment.

VirtualBox Installation

Create a new virtual machine and select Type: Other and Version: Other (64-bit). I recommend the following settings:

• 2 CPUs
• 10GB hard disk
• 2GB RAM
• 128MB video memory
• Bridged network adapter

For Haiku OS installation, create a Be File System (BFS) partition on your virtual hard disk and install Haiku on it.

Initial clicks inside the Haiku OS window will capture your mouse. To release it, press the Right Ctrl key on your keyboard.

Adding VirtualBox Guest Additions

After starting Haiku OS, open Haiku Depot, select all packages, and enter virtualbox in the search box. After installing the additions, you will gain two very useful features: mouse integration and dynamic screen resolution.

Mouse integration works automatically, but dynamic resolution needs to be manually configured. Open Haiku's Desktop Applets and run VBoxTray. Then, go to the VirtualBox View menu and select Auto-resize Guest Display.

Enabling SSH Access

To enable SSH access, you first need to determine the IP address of your Haiku system. Since Haiku's terminal runs bash and supports basic Unix commands, simply type:

ifconfig

Next, install and start the SSH daemon.

Installing and Running sshd

pkgman install openssh
/bin/sshd

The first command installs the SSH daemon into the /bin folder, and the second one starts it.

Configuring sshd for Password Login

You’ll log in using Haiku’s default user, named user. Since Haiku is a single-user system, this default account doesn’t have a password. You’ll need to create one by typing:

passwd

After setting your password, you must enable password authentication for SSH login. Open the Haiku SSH configuration file:

nano /system/settings/ssh/sshd_config

Yes, Haiku OS comes with the beloved nano editor by default.

Find and modify (or add) the following lines:

PasswordAuthentication yes
ChallengeResponseAuthentication yes
PermitRootLogin yes
PubkeyAuthentication yes

Next, restart the SSH daemon. First, find its process ID (replace sshd-process-id with the actual process ID in the example below):

ps | grep sshd
kill sshd-process_id
/bin/sshd

You can now test password login from your Linux PC (replace your-haiku-ip with the IP address of your Haiku machine):

ssh user@your-haiku-ip

Logging in via SSH Without a Password

Since you’ll likely use your Haiku system for debugging, you probably don’t want to enter your username and password every time. To set up SSH key-based authentication, follow these steps.

On your Linux PC, generate a new SSH key:

ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa

When prompted for a passphrase, just press Enter twice to leave it empty. Then copy the public key to your Haiku system:

ssh-copy-id -i ~/.ssh/id_rsa.pub user@your-haiku-ip

Now, edit the Haiku SSH configuration file again:

nano /system/settings/ssh/sshd_config

Update it to:

PasswordAuthentication no
ChallengeResponseAuthentication no
PermitRootLogin prohibit-password
PubkeyAuthentication yes
AuthorizedKeysFile boot/home/.ssh/authorized_keys

Restart sshd, and you should now be able to log in without a password.

A Touch of Elegance

If you don’t want to type the IP address every time, you can optionally create a name for your Haiku machine that SSH will recognize. You can set this up in two places.

Let’s assume your IP address is 192.168.1.149.

You can either edit the /etc/hosts file and add a mapping for your IP address:

192.168.1.149 haiku-vm

Or you can create a ~/.ssh/config file with the following content:

Host haiku-vm
    HostName 192.168.1.149
    User user
    IdentityFile ~/.ssh/id_rsa
    IdentitiesOnly yes
    RequestTTY force

Both methods will allow you to use haiku-vm as the host name. You can now test the connection by running:

ssh user@haiku-vm

Installing Tools on Haiku OS

Haiku brings its own compilation suite including gcc and g++, but you will need to add gdb, cmake, and rsync on your. Go to your Haiku Terminal and type

pkgman install cmake
pkgman install gdb
pkgman install rsync

pkgman is a command line version of the Haiku Depot for those of us who prefer using the command line.

Congratulations! Your Haiku system is now ready for development.

Set Up Your Project in Visual Studio Code

Now it's time to prepare the project you will compile and debug on your Haiku machine. This will be a simple C++ program located inside the src/ directory that displays a basic message in a window.

Hello Haiku

Below is the C++ code for our main.cpp.

#include <Application.h>
#include <Window.h>
#include <View.h>
#include <StringView.h>

class HelloWorldWindow : public BWindow {
public:
    HelloWorldWindow()
        : BWindow(BRect(100, 100, 400, 200), "Hello Haiku", B_TITLED_WINDOW, B_QUIT_ON_WINDOW_CLOSE) {
        BView* background = new BView(Bounds(), "background", B_FOLLOW_ALL, B_WILL_DRAW);
        background->SetViewColor(ui_color(B_PANEL_BACKGROUND_COLOR));
        AddChild(background);
        
        BStringView* helloText = new BStringView(BRect(20, 20, 280, 40), "hello", "Hello Haiku!");
        background->AddChild(helloText);
    }
};

class HelloWorldApp : public BApplication {
public:
    HelloWorldApp() : BApplication("application/x-vnd.HelloHaiku") {}

    void ReadyToRun() {
        HelloWorldWindow* window = new HelloWorldWindow();
        window->Show();
    }
};

int main() {
    HelloWorldApp app;
    app.Run();
    return 0;
}

CMakeLists.txt

Now create the CMakeLists.txt file in the root directory to build the program.

cmake_minimum_required(VERSION 3.10)

# Project Name
project(HaikuSexProject)

# Set C++ standard
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Target system (Haiku)
set(CMAKE_SYSTEM_NAME Haiku)

# Set Debug Build Type
if(NOT CMAKE_BUILD_TYPE)
    set(CMAKE_BUILD_TYPE Debug)
endif()

# Define source files
set(SRC_FILES src/main.cpp)

# Add the executable
add_executable(HaikuSex ${SRC_FILES})

# Find Haiku system include directories and libraries
find_path(HAIKU_INCLUDE_DIR NAMES app/Application.h PATHS /boot/system/develop/headers/be)
find_library(HAIKU_LIB_BE NAMES be PATHS /boot/system/develop/lib)

# Include Haiku headers
target_include_directories(HaikuSex PRIVATE ${HAIKU_INCLUDE_DIR})

# Link against Haiku's BeAPI
target_link_libraries(HaikuSex PRIVATE ${HAIKU_LIB_BE})

It's time to create our tasks.json and launch.json files.

tasks.json

There are two tasks that need to be executed before we can start debugging our software:

• We need to copy all source code files to the Haiku machine.
• We need to run g++ on the Haiku machine and compile the code there.

Here is the file that accomplishes this:

{
    "version": "2.0.0",

    "tasks": [
        {
            "label": "Sync to Haiku VM (rsync)",
            "type": "shell",
            "command": "rsync",
            "args": [
                "-avz",
                "--rsync-path=/boot/system/bin/rsync",
                "-e",
                "ssh -T -o 'RemoteCommand=none' -o 'RequestTTY=no'",
                "/media/tomaz/Work/sex/",
                "user@haiku-vm:/boot/home/Projects/sex/"
            ],
            "problemMatcher": [],
            "group": {
                "kind": "build",
                "isDefault": false
            }
        },
        {
            "label": "CMake Configure (Haiku VM)",
            "type": "shell",
            "command": "ssh",
            "args": [
                "user@haiku-vm",
                "cd /boot/home/Projects/sex/ && cmake -B build -G \"Unix Makefiles\" -DCMAKE_BUILD_TYPE=Debug"
            ],
            "problemMatcher": [],
            "dependsOn": ["Sync to Haiku VM (rsync)"]
        },
        {
            "label": "Build (Haiku VM)",
            "type": "process",
            "command": "bash",
            "args": [
                "-c",
                "ssh user@haiku-vm 'cd /boot/home/Projects/sex/build && make -j4' | sed 's|/boot/home/Projects/sex|/media/tomaz/Work/sex|g'"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": "$gcc",
            "dependsOn": ["CMake Configure (Haiku VM)"]
        }
    ]
}

The Sync to Haiku VM (rsync) task uses rsync to copy the the project to the Haiku machine.

Only files that have changed are copied.

The next task, called CMake Configure (Haiku VM), runs CMake on the Haiku machine to generate a Makefile for the project.

Finally, the Build (Haiku VM) task executes make on the Makefile generated in the previous step and uses set to re-map paths from the Haiku station to your Linux PC.

All tasks are interdependent. After executing all three, you should have a built version of your software on the haiku-vm machine.

You need to change the folders in the tasks.json and create an empty directory on Haiku. The rsync will not do that for you.

launch.json

After defining the VSCode tasks, we need to create a launch configuration to run and debug the software on the Haiku machine. Before proceeding, make sure you have the Native Debug extension installed in your VSCode.

This configuration assumes your program is located in the /boot/home/Projects/first directory, with the executable inside the build/myprogram subdirectory.

It maps the source directories in the debug information inside the executable to the corresponding directory on the Haiku machine. All gdb traffic is routed through an SSH channel to the integrated terminal in VSCode.

Finally, it compiles your software before starting the debugging session.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug on Haiku VM",
            "type": "cppdbg",
            "request": "launch", // You can switch this to "attach" later
            "program": "/boot/home/Projects/sex/build/src/core/HaikuSex",
            "cwd": "/boot/home/Projects/sex/build/",
            "MIMode": "gdb",
            "ssh": {
                "host": "haiku-vm",
                "user": "user"
            },
            "pipeTransport": {
                "pipeProgram": "ssh",
                "pipeArgs": [
                    "-T",
                    "user@haiku-vm"
                ],
                "debuggerPath": "/bin/gdb"
            },
            "setupCommands": [
                {
                    "text": "-exec set pagination off",
                    "description": "Disable pagination",
                    "ignoreFailures": true
                },
                {
                    "text": "-gdb-set scheduler-locking on",
                    "description": "Lock scheduler for single thread stepping",
                    "ignoreFailures": true
                }
            ],
            "sourceFileMap": {
                "/boot/home/Projects/sex/": "${workspaceFolder}"
            },
            "preLaunchTask": "Build (Haiku VM)",
            "console": "integratedTerminal",
            "externalConsole": false,
            "stopAtEntry": true
        }
    ]
}

Finale

Believe it or not, we're done! You can now use this rather unconventional method to debug Haiku software.

The conventional approach would be to use gdbserver, but it is not stable at the moment.

All that’s left is to start your Haiku virtual machine, open VSCode, and run the program.

Finally, here is a link to the GitHub repository containing a working version.

Here’s how the repair went.

What I Found

It was obvious that this Spectrum had been worked on before—several times, by different people. The PCB had a ton of flux residue, and the soldering quality was all over the place. There were factory-original joints, some relatively clean repairs, and some truly messy ones.

The worst soldering jobs were on:

• DRAM chips
• One of the upper RAM chips
• The ULA
• The CPU

And TR4 was missing altogether.

Power Problems

To see what I was dealing with, I plugged in a diagnostics module. It immediately flagged missing 12V and -5V power rails. With TR4 missing, this wasn’t a shock. After soldering in a replacement TR4, the 12V rail came back, but the -5V rail was still reading -1.5V. There was a high-pitched whining sound coming from the board, most likely from the coil.

I checked the schematics and replaced two capacitors (C46 and C47), then tested the diodes D11 and D12. D11 turned out to be shorted. Replacing it fixed the -5V rail, and the whining stopped.

RAM Troubles

The diagnostics now reported issues with the lower DRAM. I started removing the lower RAM chips, and that’s where things got ugly. The traces under the chips were already damaged, and my desoldering work made it worse, especially on the last chip. I ended up having to rebuild the damaged traces with thin copper wire. Once that was done, I soldered IC sockets over the repaired area, which went fine, but the damage was done. My heart was broken.

I inserted a DRAM module into the sockets and ran the diagnostics again. The lower RAM test passed, but the upper RAM test flagged errors. The screen was scrambled.

I clipped the legs off the upper RAM chips and removed them without causing any additional damage. At this point, the board was effectively running as a 16K Spectrum.

Scrambled Screen and ULA Issues

With the upper RAM out of the equation, I was now working with a 16K Spectrum. The diagnostics passed the lower RAM tests, but the display was a mess. This suggested the CPU could access the RAM without issues, but the ULA could not.

I also noticed something strange: if I swapped the DRAM module for individual 4116 chips, they were all flagged as broken. This didn’t provide any additional clues, but my money was still on the ULA. I didn’t pretend to fully understand how a broken ULA affects the board.

So, I desoldered the ULA and replaced it with a socket (thankfully without causing any damage this time). After swapping in a known-good ULA, the scrambled screen problem disappeared, and the Spectrum was finally working properly.

What Was Fixed

Here’s the rundown of everything that needed repair on this ZX Spectrum Issue 2:

• TR4: Missing, replaced.
• D11: Shorted, replaced.
• Lower RAM: Rebuilt damaged traces, added IC sockets, replaced chips.
• ULA: Replaced.
• Upper RAM: Removed for now; further work needed.
• My heart: Broken. Unable to fix.

I haven’t restored the upper RAM yet, but at this point, I’m confident it’ll be straightforward. I tested the DRAM chips I removed earlier—half of them were dead. While that’s some consolation, I regret not clipping their legs in the first place.

Takeaways

1. Diagnose First: A diagnostics module makes troubleshooting much easier.
2. Be Careful with RAM Chips: Clipping the legs before desoldering can save you a lot of headaches.
3. Watch Out for the ULA: It can cause some weird issues that aren’t immediately obvious.
4. Fixing Old Tech Isn’t Always Pretty: Sometimes it’s a battle, but it’s worth it.

This repair wasn’t perfect, and it wasn’t pretty, but the Spectrum works again. If you’re restoring one of these old machines, just take it slow, learn from your mistakes, and don’t beat yourself up too much if things don’t go perfectly.

Introduction

In this second part of our retro game programming series, we'll look at implementing double buffering with page switching. Double buffering is a technique where you draw your game screen into a buffer, and then quickly copy the entire buffer onto the screen to prevent flickering. If the computer supports multiple video memory pages then your buffer is the next page and the switch is implemented in hardware, costs no additional CPU cycles, and is very fast.

In this article, we'll assume two pages and the ability to tell the system which page is currently being drawn to and which page is currently displayed. We'll then alternate between the drawing page and the display page to implement the switching.

Platform Specifics

Let's start our journey by defining our platform-specific functions.

The function gsetpage(pg_type, pg_no) sets the current page. Valid values for pg_type are PG_DISPLAY for the page currently displayed, and PG_WRITE for the page to which all graphical operations go. These two values are bitmasks, so you can use them together. In other words, you can call the function like this: gsetpage(PG_DISPLAY|PG_WRITE, 0). Since we're assuming we only have two pages, the valid values for pg_no are 0 and 1.

Function gsetcolor(color) accepts only two values: CO_FORE for foreground color, and CO_BACK for background color. Drawing with the background color effectively erases the content. Finally, function gcls() clears the write page.

Now let us use all of them to write the clear screen function.

void clear_screen()
{
    gsetpage(PG_WRITE,0);
    gcls();
    gsetpage(PG_WRITE,1);
    gcls();
    gsetpage(PG_DISPLAY,0);
    gsetcolor(CO_FORE);
}

The Game State

We need a structure to store our game state. For simplicity, let's assume that we are only going to draw one sprite. Our game state structure, therefore, needs at least three members: the current display page, the current sprite position, and the previous sprite position.

Why do we need the previous sprite position? Because we will be drawing to a different page each cycle. And when we draw the next page, we will need to erase the previous content. The previous coordinates will help us with this task.

Our game structure will look like this:

typedef struct game_s {
    uint8_t page;
    int x;
    int y;
    int prevx;
    int prevy;
}

Following figure demonstrates our algorithm.

Implementation

We are now finally ready to implement our game loop. We will start by initializing the game structure. Then we will enter the loop and alternately display the current page and prepare the next page for displaying. We will use data from the previous page for content removal and data from the current page for calculating the next sprite position.

void game_loop() {

    /* remember our clear screen? */
    clear_screen();

    /* initialize game at position 0,0 */
    game_t g = { 0, 0, 0, 0, 0 };

    /* first display page to 1, but write page to 0 */
    gsetpage(PG_DISPLAY,1);
    gsetpage(PG_WRITE,g.page);

    /* is there previous game state? */
    bool has_prev_state = false;

    while(1) {

        /* set color to foreground */
        gsetcolor(CO_FORE);
        
        /* you need to provide function draw_sprite to draw sprite
           at position x,y */
        draw_sprite(g.x, g.y);
        
        /* show drawn page */
        gsetpage(PG_DISPLAY,g.page);

        /* set next page as drawing page */
        g.page = g.page ? 0 : 1;
        gsetpage(PG_WRITE,g.page);

        /* delete previous lines? */
        if (has_prev_state) {
            /* setting color to CO_BACK will delete everything
               drawn previously. */
            gsetcolor(CO_BACK);
            /* and erase sprite using previous coordinates */
            draw_sprite(g.prevx, g.prevy);
        } else 
            has_prev_state=true;

        /* store prev. state  */
        g.prevx=g.x; g.prevy=g.y;
        
        /* your function to calculate next sprite position
           and set g.x and g.y */
        calc_next_sprite_position(&g);

        /* game over? */
        if (end_of_game()) break;
    }
}

Retro Game Programming Tips, Part 1: The Game Clock

Introduction

In today's world of high-resolution graphics and advanced GPUs, it's easy to forget the humble beginnings of computer graphics. One such piece of history is the Iskra Delta Partner, a 40-year-old computer with a Thomson EF9367 Graphical Display Processor (GDP) that can only draw lines. The constraints of this system make programming for it an exotic and intriguing challenge, as there is no raster support. It's almost like working with a vector display, where everything must be drawn using lines only.

The EF9367 chip supports raster operations and text. However, in the Iskra Delta Partner, raster functionality is disabled. Furthermore, the chip is limited to a single 5x7 font, which it renders internally using lines alone. This approach lacks clipping capabilities, rendering it unsuitable for windowing graphical user interfaces.

In this series we will develop a 2D graphics library and support tools for the Iskra Delta Partner.

Our initial task for the Part 1 of the series is to develop a tool that, when provided with a PNG image, converts it into lines, essentially vectorizing the image.

Prerequisites

To fully grasp the concepts presented, you should have a basic understanding of the graph theory and know C++, CMake and git.

We will develop on Linux using modern C++ and the CMake build system. Therefore, you will need the latest version of either g++ or clang, with support for the C++20 standard.

We will use Patrick Boettcher's header only command line argument parser library.

The Standard C++ library lacks images processing capabilities, so we will use Sean Barrett's header-only libraries to address this limitation. These libraries enables us to read a PNG file and convert it into a raw RGB array, which can then be traversed and processed as needed.

Our objective is to examine algorithms more closely, which will involve some raw programming. For professional development, using OpenCV would be a more suitable option, as it already has most of the algorithms implemented.

The URL for our Git repository is https://github.com/tstih/gpxtools. If you clone it using the --recursive switch, the mentioned libraries will be downloaded as submodules

Problem analysis

Let us examine the process of rendering a mouse cursor on a raster single bit-per-pixel display. Typically, this involves two bitmaps: the cursor and the mask. First, the mask is transferred to the screen using an OR operation, which sets all mouse pixels to black. Next, the cursor is copied using a NAND operation, which clears the interior of the mouse cursor. The figure below illustrates the resulting image.

There are several methods we can employ to draw this cursor using only lines.

First, we could represent each pixel as a horizontal line with a width of one pixel. To draw the mouse cursor in this manner, from left to right and top to bottom, we would need to create 45 lines, change the color 17 times, and reposition the cursor without drawing the line 11 times. Clearly, sending 73 commands to the Graphics Display Processor (GDP) is a costly approach for drawing a simple 7x10 pixel mouse cursor.

Alternatively, we could attempt to draw all pixels of the same color using a single horizontal line. For instance, instead of drawing three white pixels individually, we would draw one line spanning three pixels in length. This approach would decrease the number of drawing commands sent to the Graphics Display Processor (GDP) from 45 to 29. However, it would not affect the number of times we need to change the color or reposition the cursor without drawing. Using 57 commands is still very expensive.

As we delve into the proposed algorithm, it becomes clear that these solutions aren't the best. We've come to this realization because, honestly, we can draw the mouse cursor ourselves in under 20 strokes, which is way more efficient. So, in this part of the article, let's try to come up with better solution to tackle this problem. And in the next part, we're going to take it up a notch and optimize the solution by diving into the world of graphs. Exciting stuff, right?

Blob detector

Points that don't "adhere together" cannot form lines. To narrow down the search space for line detection, our initial step is to identify pixels that "cling together." We accomplish this by performing a simple blob detection process.

The subsequent code loads the PNG image utilizing the STB library.

image::image(std::string path) {
    int channels;
    data_ = ::stbi_load(
        path.c_str(), 
        &width_, 
        &height_, 
        &channels, 
        1); // This will convert any image to grayscale!

    if (data_ == nullptr)
        throw exception("Unable to read image.");
}

Before processing, the image is converted to grayscale. After loading the image, we identify groups of pixels that "adhere together" and return a vector of offsets from the beginning of the image in memory using the provided code.

std::vector < std::vector < int > > blobs(
    const image& img, 
    uint8_t threshold);
{
    // First create data structure to store bulk pixels.
    uint16_t w = img.width(), h = img.height();
    int len = w * h;
    uint8_t pixels[len];
    union_t < uint8_t > id;

    // Pass 1: Loop through pixels.
    int index = 0;
    uint8_t *pimg = img.data(), *ppix = pixels;
    for (uint16_t y = 0; y < h; y++)
        for (uint16_t x = 0; x < w; x++)
        {
            // Default is white...
            *ppix = 0;
            if (is_black(pimg, threshold))
            {
                // Get left top, top, right top and left values
                uint8_t
                    lt = y && x ? *(ppix - w - 1) : 0,
                    t = y ? *(ppix - w) : 0,
                    rt = y && (x < w) ? *(ppix - w + 1) : 0,
                    l = x ? *(ppix - 1) : 0;
                // Set the value!
                if (lt)
                    *ppix = lt;
                else if (t)
                    *ppix = t;
                else if (rt)
                    *ppix = rt;
                else if (l)
                    *ppix = l;
                else
                    *ppix = ++index;
                // And create equiv, if any detected.
                uint8_t c = *ppix;
                if (c != t && t)
                    id.merge(c, t); // Top check.
                if (c != rt && rt)
                    id.merge(c, rt); // Right top check.
                if (c != l && l)
                    id.merge(c, l); // Left check.
            }
            pimg++;
            ppix++;
        }

    // Pass 2: Resolve identities and generate the result.
    ppix = pixels;
    uint8_t c, root;
    std::map < uint8_t,std::vector < int > > group;
    while (len--)
    {
        // Is there a pixel?
        if (c = *ppix) {
            if ((root = id.find(c)) != c && root)
                *ppix = root;
            // Add offset to map.
            group[*ppix].push_back(ppix-pixels);
        }
        ppix++;
    }

    // Finally, restructure the result.
    std::vector < std::vector < int > > result;
    for (auto& kv : group) {
        result.push_back(kv.second);
    }
    return result;
}

You can view the complete source code on GitHub. This implementation utilizes the union-find (disjoint-set) data structure.

After running our blob detector on an image to extract individual features...

...we can focus our efforts on drawing each feature individually.

Notice that numerous features in this image exhibit similarity, albeit being drawn at different positions. For specific images showcasing repetitive patterns, this allows for feature compression.

Line detector

We will employ a custom graph algorithm specifically designed for line detection in this task. Here's a step-by-step breakdown of the algorithm:

For each blob...

1. Get first unused pixel
2. Find the point that is farthest away from pixel A by calculating the distance in pixels, considering the shorter of the horizontal and vertical distances.
3. Employ the Bresenham line algorithm to iterate from pixel A to pixel B. Check if all the pixels between A and B are present in the pixel set. If they are, a line has been detected.
4. If the pixels between A and B are not found, proceed to find the next farthest pixel and repeat the process.
5. If the distance between A and B is 2, then this constitutes a line.
6. If A==B then detect a pixel as the line.

And the implementation in C.

std::vector < std::pair < int,int > > vectorize(
    const image &img,           // The image.
    std::vector < int > pixels,    // The stroke.
    uint8_t threshold){         // Black pixel threshold.

    // Result is a vector of pair of points.
    std::vector < std::pair < int,int > > lines;

    // Vector should already be sorted if coming from blobs.
    std::sort(pixels.begin(), pixels.end());

    // Used, unused and visited pixels. Initialize unset to pixels.
    std::set < int > used, visited, unused(pixels.begin(),pixels.end());

    // Get first element.
    auto pstart=*unused.begin();
    while (!unused.empty()) { // While there are any pixels inside.
        auto pend=furthest_point(pstart, img, unused, threshold);
        if (pstart==pend) {
            // If not already used...
            std::pair < int,int > line={pstart,pend};
            lines.push_back(line);
            // Restore all visited nodes.
            move_elem(visited, unused);
            // Unused to used.
            move_elem(unused, used, pstart);
            // Take next.
            if (!unused.empty()) pstart=*(unused.begin());
        } else {
            // Try to match the line.
            auto line=match_line(pstart,pend, img, unused, threshold);
            if (line.empty()) { // No match -> remove end and retry.
                move_elem(unused, visited, pend);
            } else { // Yuuperoo. A match.
                // Push line to lines.
                lines.push_back(std::make_pair(pstart,pend));
                // Restore all visited nodes.
                move_elem(visited, unused);
                // Move all matched pixels to used.
                move_elem(unused,used,line);
                // Take next.
                if (!unused.empty()) pstart=*(unused.begin());
            }
        }
    }
    // Return result.
    return lines;
}

Conclusion

Our vectorization algorithms are now complete. To convert an image into lines, we can utilize both algorithms sequentially.

// Source image.
ga::image src=ga::image("my-image.png");
// Extract blobs.
auto result=ga::blobs(src, 32);
// Now convert each blob to a vector of lines.
int i=0;
for(auto blob:result) {
    // NOTE: each line is represented by two offsets (integers)
    //       into the raw bpp image.
    auto lines=ga::vectorize(src,blob,32);
}

While this approach is functional, it is not currently optimized. Let's conclude this article by highlighting two weaknesses that we will address in the next part, where we will delve into graph theory to generate optimal drawing paths for glyphs on the Iskra Delta Partner.

Connect detected lines

Consider the following scenario: on the left, you have the original image, while on the right, you can see the result of our vectorization process, which has detected two lines.

Our vectorization correctly identified two lines, but drawing them involves four graphical commands. The first command moves to the position (1,1), the next one draws a line to (1,6), followed by a move to (2,6), and finally, another command to draw the line to (6,6). Since we already know that the line continues from (1,6) to (6,6), the move operation to (2,6) is unnecessary. We could simply extend the horizontal line by one pixel, saving one graphical command.

Optimize intersections

Because our algorithm keeps track of previously visited pixels, it does not handle line intersections correctly, as demonstrated in the images below:

The first image illustrates two intersecting lines. In the second image, you can observe the output of our algorithm: three non-intersecting lines. The final image displays the optimal result.

Surprisingly, I managed to persuade my daughter to help me assemble the kit. She was even more pumped about it than I was. The assembly itself was fairly straightforward, taking just a couple of hours, thanks to the well-structured instructions. However, our Galaksija didn't show up on the TV screen when we turned it on for the first time.

As with any DIY project, things don't always go smoothly. After some troubleshooting and tinkering, I figured out that I needed to tweak resistor R9 and swap out integrated circuits U2 (74LS04) and U3 (74LS74). The reasons behind these modifications remained a puzzle for me, and we left it at that, at least for the time being. Nevertheless, a closer look at the original building instructions (http://www.voja.rs/galaksija/0102.htm) does reveal a passage connecting R9 to image synchronization.

The Galaksija kit offered a mix of nostalgia, technical challenges, and a chance to explore together with my daughter. While the modifications remain a puzzle, it's a challenge I'm open to revisiting in the future. If you're looking for a hands-on journey into the world of retro computing, a project like this could be just what you need.

A while ago, we decided to bring back the Iskra Delta Partner, a Slovene computer from the 1980s. Most people have never heard of it, and that is partly the point. It was not famous. But it was ours. And like all forgotten machines, it had something to teach us.

Our goal was ambitious. We wanted to replicate the motherboard exactly. Not emulate, not approximate. Recreate it, down to the last via. That turned out to be more work than it sounds. The board had more than a thousand vias, which are the tiny copper bridges that connect different layers of the circuit. Placing them manually in KiCad quickly became a grind. The kind of work that makes you question why you started in the first place.

So we did what any curious programmer would do. We automated it.

The Usual Way

Normally, you take a scan of the board, load it into KiCad, and begin tracing. You connect the pads, draw the tracks, and slowly add each via by hand. It is tedious in the way that sanding wood with a toothbrush is tedious. Not difficult, just slow and repetitive. And when you are doing it more than a thousand times, it starts to feel less like engineering and more like penance.

After a few hours, I realized I was spending all my time searching for tiny, identical holes and placing them one by one. It was detailed work, but not intellectually demanding. My focus would drift while my hand kept moving. It felt inefficient to do something so purely visual by hand, especially when I had a computer nearby that could probably be taught to do it better.

Using Computer Vision

We started with OpenCV. It is a solid library filled with useful tools for image processing. On our first scanned image, it worked surprisingly well. The algorithm identified the vias with decent accuracy. It felt like a small miracle.

Then we tried a different image. And it stopped working.

The problem was simple but hard to avoid. The lighting, contrast, and resolution change from one image to another. What worked in one case completely failed in another. So we set OpenCV aside and built our own solution.

The Algorithm (It Is Simpler Than You Think)

At the core, our algorithm is a moving window. We drag a small square across the entire image and ask, "Does this square contain a via?"

To answer that, we describe the contents of each square using a feature vector with histogram-like features. It is like turning the square into a list of numbers that summarize what it looks like. Then we compare that list to examples of known vias. We only needed to mark around ten of them by hand. That was enough.

We measure the similarity using cosine similarity. If the square looks enough like the examples, we mark it as a via. It worked. In one run, we found around 970 out of 1000 vias. Automatically. In minutes.

The Unexpected Improvement

The biggest boost did not come from tweaking the similarity metric or adding more training data. It came from doing something much simpler.

We told the algorithm where not to look.

We created what we call a tabu mask. It is a kind of map that marks off areas where vias cannot be. We built it from the traces in the image. When we excluded those areas from the search, the accuracy improved dramatically. The process became faster too.

Removing noise is just as important as finding signal.

Why This Matters

This project was never about publishing a paper or building a product. It was about solving an interesting problem. We wanted to bring a computer back to life. And along the way, we found ourselves solving a tiny computer vision problem that no one else cared about. That is what made it fun.

In the end, the code worked. It helped us finish the board faster, with less frustration. And we felt something that is increasingly rare in modern tech: satisfaction. Not from likes or retweets or investor interest. Just from the quiet feeling of making something work.

Try It Yourself

We have published the code. It is all in one file. If you know basic machine learning, you will understand it. It is not fancy. It is not the latest thing. But it works.

If you are interested in more advanced methods, there are neural networks that can detect anything in any image with remarkable accuracy. But if you just want to find a thousand dots on a circuit board scan, this is probably enough.

And most of the time, enough is exactly what you need.

Resources

• Project GitHub repository

Read Also

• Recreating the IDP Motherboard

The Iskra Delta Partner computer supports vector graphics and has the capability to draw green lines on a black background.

When porting a game from an 8-bit microcomputer with full colors to the Iskra Delta Partner, you have the option to manually create sprites based on color sprites. Nevertheless, there are instances where it's feasible to automatically or semi-automatically convert them. This text elaborates on one such technique.

In this project, we will be working with a sprite sheet obtained from the internet, featuring various sprites from the game of Karate. These sprites showcase several dominant colors, including both light and dark shades, such as red, black, white, gray, and two skin tones.

Our goal is to simplify the image by creating two distinct groups of colors: one for the light colors, which includes white and skin tones, and the other for the darker colors, encompassing red and black. Through a filtering process, we will selectively remove all colors except those we group into the white and black categories. As a result, we will obtain multiple images, each containing only the elements corresponding to the colors in the selected group. All other colors will be removed from these images.

Let us now commence with our transformation process.

1. Outline Sprites

The initial step involves locating the bounds of each sprite and outlining it. We achieve this by employing blob detection and subsequently determining the sprite polygon.

2. Isolating the Black Group

To proceed, we will now isolate the black color group (comprising red and black colors) as polygons and proceed to fill them.

3. Isolating the White Group

We will proceed to isolate the polygons belonging to the white color group and then outline them.

4. Merge Image and Overlays

Now, let's merge the outline and the two overlay images to create the final image.

And there you have it – the sprites are now converted. If you had a raster, you could also utilize hatch lines (patterns like 10101010) to create additional group colors. However, for the Iskra Delta Partner, we only used two groups because drawing other patterns would be too slow. Wishing you a happy converting experience!

Retro computer games are characterized by their vivid visuals, featuring flying spaceships, blinking rocket thrusts, falling meteors, bullets soaring through the air, and explosions happening all around. The elements in these games can move at various speeds, and while the effects are temporary, the gameplay itself remains constant.

In this article, we'll explore a simple trick to synchronize all these elements using a straightforward game clock. Let's begin by defining the clock.

#define MAX_CYCLES 10
int clock = MAX_CYCLES;
bool game_over = false;

void main()
{
    while (!game_over)
    {
        if (!--clock)
            clock = MAX_CYCLES;
    }
}

In the provided code, the clock serves as a straightforward counter that counts down to zero and resets once it reaches that point. If you have two sprites, A and B, and sprite A needs to move twice as fast as sprite B, the simplest solution is to move sprite A every clock cycle and sprite B every second clock cycle. Here's how it works:

#define MAX_CYCLES 10
int clock = MAX_CYCLES;
bool game_over = false;

void main()
{
    while (!game_over)
    {
        printf("Move A\n");
        if (clock & 1) printf("Move B\n");
        if (!--clock)
            clock = MAX_CYCLES;
    }
}

Great job! You've successfully created your first game synchronization mechanism. It's quite simple, but not very versatile. Now, let's enhance its flexibility by providing a separate clock counter for each sprite and/or event that requires synchronization.

To achieve this, we'll use a typedef structure called "clk_t," which includes the following components:

• ncycles: The total number of cycles for the clock.
• cycle: The current cycle count for the clock.
• action: A function pointer that specifies the action to be performed.

Additionally, we'll create an array of pointers to these clocks, allowing us to manage multiple clocks simultaneously. We'll set a predefined value, NUM_CLOCKS, to determine the maximum number of clocks available in the system.

Here's the updated code:

typedef struct clk_s
{
    int ncycles;
    int cycle;
    void (*action)();
} clk_t;

/* create an array of pointers to clocks*/
#define NUM_CLOCKS 10
clk_t *clocks[NUM_CLOCKS];

/* initialize all clocks to NULL */
void clk_init()
{
    for (int i = 0; i < NUM_CLOCKS; i++)
        clocks[i] = NULL;
}

Now that we have the initial data structures in place, let's proceed to create functions for managing the clocks. We need to implement functions to create a new clock and add it to the clocks array, destroy a clock and remove it from the array, and also update the clock ticks.

Here's the code:

static int _clk_find(clk_t *c)
{
    for (int i = 0; i < NUM_CLOCKS; i++)
        if (clocks[i] == c)
            return i;
    return -1;
}

clk_t *clk_create(int ncycles, void (*action)())
{
    /* find empty slot */
    int pos = _clk_find(NULL);
    if (pos >= 0)
    {
        /* allocate clock */
        clk_t *clk = malloc(sizeof(clk_t));
        clk->cycle = clk->ncycles = ncycles;
        clk->action = action;
        /* and add ptr to array */
        clocks[pos] = clk;
        /* return pointer */
        return clk;
    }
    /* not found! */
    return NULL;
}

void clk_destroy(clk_t *c)
{
    int pos=_clk_find(c);
    if (pos >= 0)
        clocks[pos] = NULL;
    free(c);
}

void clk_tick() {
    for (int i = 0; i < NUM_CLOCKS; i++) {
        if (clocks[i]) { /* not NULL */
            clocks[i]->cycle--; /* reduce cycle */
            if (!(clocks[i]->cycle)) {
                clocks[i]->action();
                clocks[i]->cycle=clocks[i]->ncycles;
            }
        }
    }
}

With these functions, you can effortlessly create and manage multiple clocks within your retro game. Each clock can be assigned its specific cycle count and associated action, enabling you to synchronize various game elements and events seamlessly. Let's see how the main program would utilize these functions:

void move_a() { printf ("Move A\n"); }
void move_b() { printf ("Move B\n"); }
int game_over=100;

void main() {
    clk_init();
    clk_t* a=clk_create(1,&move_a);
    clk_t* b=clk_create(2,&move_b);
    while(!game_over--)
        clk_tick();
    clk_destroy(a);
    clk_destroy(b);
}

Now, we have separate clocks for each event, and they are all synchronized with the same game clock. This forms the fundamental concept behind the game clock. Of course, on your platform, you have the option to write these functions in assembly instead of C, which would make them even faster. After all, this code will be responsible for controlling every particle of an exploding object on the screen.

Let's consider a scenario where we are developing the Moon Lander game, and we want to apply gravity to a sprite. Consequently, with each turn, the lander will fall faster and faster due to the applied gravity. As the lander's movement is governed by the clock, the clock must adapt accordingly. So, let's include a function that allows us to modify the clock.

void clk_change(clk_t *c, int ncycles2) {
    c->ncycles2=ncycles2;
}

But wait?! What's that ncycles2? This represents a pending change of the clock period. By adding this variable, we ensure that if the clock period changes in the middle of a cycle, the current cycle will complete before switching to the new clock period.

For this mechanism to function correctly, we need to modify the clk_t type and the functions responsible for creating clocks and handling clock ticks.

Here's the updated code:

typedef struct clk_s
{
    int ncycles;
    int ncycles2;
    int cycle;
    void (*action)(game_context_t *ctx);
} clk_t;

clk_t *clk_create(int ncycles, void (*action)(game_context_t *ctx))
{
    /* Find an empty slot in the array */
    int pos = _clk_find(NULL);
    if (pos >= 0)
    {
        /* Allocate memory for the new clock */
        clk_t *clk = malloc(sizeof(clk_t));
        clk->cycle = clk->ncycles = clk->ncycles2 = ncycles;
        clk->action = action;

        /* Add the pointer to the clocks array */
        clocks[pos] = clk;

        /* Return the pointer to the new clock */
        return clk;
    }
    return NULL;
}

void clk_tick(game_context_t *ctx)
{
    for (int i = 0; i < NUM_CLOCKS; i++)
    {
        if (clocks[i]) /* Check if the clock is not NULL */
        {
            clocks[i]->cycle--; /* Reduce the cycle count */

            if (!(clocks[i]->cycle)) /* Cycle reached 0? */
            {
                clocks[i]->action(ctx);
                clocks[i]->cycle = clocks[i]->ncycles = clocks[i]->ncycles2; 
            }
        }
    }
}

Finally, we've added a pointer to the game context in all functions. This context represents the current state of the game, holding information about objects' positions, draw status, game logic, and more. Each function called by the game clock receives this context and can modify it accordingly. Here's the complete code for our game clock:

typedef struct game_context_s {
    bool game_over;
} game_context_t;

typedef struct clk_s
{
    int ncycles;
    int ncycles2;
    int cycle;
    void (*action)(game_context_t *ctx);
} clk_t;

/* create an array of pointers to clocks*/
#define NUM_CLOCKS 10
clk_t *clocks[NUM_CLOCKS];

/* initialize all clocks to NULL */
void clk_init()
{
    for (int i = 0; i < NUM_CLOCKS; i++)
        clocks[i] = NULL;
}

int _clk_find(clk_t *c)
{
    for (int i = 0; i < NUM_CLOCKS; i++)
        if (clocks[i] == c)
            return i;
    return -1;
}

clk_t *clk_create(int ncycles, void (*action)())
{
    /* find empty slot */
    int pos = _clk_find(NULL);
    if (pos >= 0)
    {
        /* allocate clock */
        clk_t *clk = malloc(sizeof(clk_t));
        clk->cycle = clk->ncycles = clk->ncycles2 = ncycles;
        clk->action = action;
        /* and add ptr to array */
        clocks[pos] = clk;
        /* return pointer */
        return clk;
    }
    /* not found! */
    return NULL;
}

void clk_destroy(clk_t *c)
{
    int pos=_clk_find(c);
    if (pos >= 0)
        clocks[pos] = NULL;
    free(c);
}

void clk_tick(game_context_t *ctx) {
    for (int i = 0; i < NUM_CLOCKS; i++) {
        if (clocks[i]) { /* not NULL */
            clocks[i]->cycle--; /* reduce cycle */
            if (!(clocks[i]->cycle)) { /* cycle reached 0? */
                clocks[i]->action(ctx);
                clocks[i]->cycle=clocks[i]->ncycles=clocks[i]->ncycles2;
            }
        }
    }
}

void clk_change(clk_t *c, int ncycles2) {
    c->ncycles2=ncycles2;
}

void move_a(game_context_t *ctx) { printf ("Move A\n"); }
void move_b(game_context_t *ctx) { printf ("Move B\n"); }

game_context_t gc={false};

int j=0;

void main() {
    clk_init();
    clk_t* a=clk_create(1,&move_a);
    clk_t* b=clk_create(3,&move_b);
    while(!gc.game_over) {
        clk_tick(&gc);
        j++;
        if (j==10) clk_change(b,1);
        if (j==20) gc.game_over=true;
    }
    clk_destroy(a);
    clk_destroy(b);
}

We've developed a simple yet powerful framework. However, up until now, we've only used it for theoretical cases. To demonstrate its practical application, here's a code fragment that shows how a game of Froggy could look using our framework:

/* Frogger */

/* Create the game context */
game_context_t *gc = gc_create();

/* Clocks for various game events */
clk_create(1, kbd_handler);  /* Scan the keyboard every tick */
clk_create(1, dead_frog);    /* Check if the frog is dead every tick */
clk_create(3, move_row1);    /* Move the first row every 3 cycles */
clk_create(5, move_row2);    /* Move the second row every 5 cycles */
clk_create(3, move_row3);    /* Move the third row every 3 cycles */
clk_create(5, move_row4);    /* Move the fourth row every 5 cycles */

/* Main game loop */
while (!gc->game_over) {
    clk_tick(gc);
    update_screen(gc);
}

And that's all there is to it. Now, all you need to do is write event handlers for each specific event, and optimize the screen update function for smooth gameplay. With this straightforward code structure and our efficient framework, you're well-equipped to develop a captivating game like Froggy. Happy coding!

Retro Game Programming Tips, Part 2: Double Buffering with Page Switching

To unravel the root cause of the erratic behavior, I opted to examine the EPROM code. Since the normal execution of the code alone couldn't account for the observed output, I began suspecting that interrupts were being triggered, diverting the code from its regular sequence. As I delved deeper into the technicalities, I discovered that the Z80 architecture incorporates two pins, INT and NMI (which receive active-low signals), through which other devices or integrated circuits (ICs) can initiate interrupts.

To identify the source of the problem, I embarked on a meticulous comparison between a functioning machine and the faulty Iskra Delta Partner. Armed with a voltmeter, I measured the INT and NMI CPU inputs. Prior to these measurements, I removed the EPROM and the CTC (Counter/Timer Circuit) from their sockets to minimize the number of variables involved.

A critical discovery emerged as I observed the voltmeter readings. On the good machine, both NMI and INT exhibited high voltage levels, indicating normal operation. However, on the problematic computer, the INT pin registered consistently low voltage levels. This discrepancy shed light on the potential cause of the computer's malfunctions.

With the INT pin identified as the culprit, I proceeded to analyze the schematics of the Iskra Delta Partner. My objective was to locate any ICs or components that could potentially be responsible for pulling the INT signal down. The overall plan was to methodically remove these components from the board, one by one, in order to observe if the faulty state persisted. Fortunately, this step turned out to be unnecessary.

Upon conducting further measurements, I uncovered that one of the logical gates responsible for transmitting the DMA interrupt signal to the CPU was faulty. It was a logical inverter 74LS04. This IC was incorrectly converting a 4.5V input to a 2.2V output, which should have been much lower, ranging from 0 to 0.4V.

With no better alternative in sight, I proceeded to replace the defective IC. Upon doing so, the INT pin on the CPU sprang back to high voltage levels. Filled with hope, I re-inserted the ICs (CTC and EPROM) and eagerly rebooted the board.

In a moment of sheer joy, the Iskra Delta Partner computer booted up flawlessly. The random crashes and boot loop were but distant memories, replaced by the smooth operation of a fully functional vintage machine. It was a testament to the power of investigation, measurement, and perseverance.

Acknowledgements

This text is (mostly) written by ChatGPT. It kind of sucks, but I rather spend my time fixing/using retro computers than typing these texts. Life is relatively short, you know.

Chapter 1: The Terminal

The Paka terminal, just as every computer terminal, serves as a communication bridge between the user and the computer. To my relief, the Paka appeared to be in decent shape. I powered it on, only to be greeted by the letter "H" on the screen, indicating a missing keyboard.

Fortunately, I managed to strike a deal with a fellow retro enthusiast, and obtained a really nice Paka keyboard. I connected the keyboard, hoping for a fully functional terminal. However, I encountered stability issues with the display, and eventually, the terminal froze. After some investigation, I discovered that the PSU was to blame.

To overcome this hurdle, I decided to connect the terminal to a modern ATX PSU, with an additional power supply for the 20V line. Miraculously, this resolved the display instability, and the terminal and keyboard appeared to be working well together. While I was eager to connect the terminal to the computer, I knew I needed a fully functional machine first.

Chapter 2: The Computer

The next step in this restoration journey was to power up the Trident computer. With all cards removed, I carefully connected the empty backplane to a power supply. To facilitate this, I devised a cable that connected the Trident to an ATX PSU, albeit without certain signals provided by the original PSU.

With the backplane connected and no immediate signs of catastrophe, I inserted the J11 board (CPU) and powered on the computer. Hoping for a glimmer of success, I observed the screen of my PC, which served as a makeshift terminal.

The terminal displayed a "hello world" message: "IDC J11 boot [d: W0] (W0,W1,F0,F1,F2,F3) >". It was a joyful moment, filled with excitement. Motivated by these promising signs of life, I proceeded to install the floppy/hard disk controller ("FD/WD").

(To be continued.)

Resources

EPROM Dumps

• Paka terminal board "KLT-T" ROMs: https://files.oddbit-retro.org/pub/Triglav/Dumps/Roms/Paka/
• Paka keyboard ROM ("0269-87"): https://files.oddbit-retro.org/pub/Triglav/Dumps/Roms/Keyboard/
• Triglav communication board (ICC) ROM: https://files.oddbit-retro.org/pub/Triglav/Dumps/Roms/ICC/
• Triglav J11 CPU board: To do.

Acknowledgements

• To do.

I restored the first Ines keyboard and documented the process.

First, let's take a look at how the I/O channels of Iskra Delta Partner are described in the IDP User's Manual. All versions of Partner come with at least one RS-232-C serial port called "LPT," which is meant to connect a serial printer. This connector is supposed to be labeled "J7" on the back of the computer. Extension option 1 includes two more serial channels (which are the same as LPT): "VAX," labeled as "J8," and "MOD," labeled as "J9." Extension options 2 and 3 include a parallel port with binary input-outputs, called "CEN," and labeled as "J6" on the back of the computer. Option "Lsyn 0002" extends Partner with a synchronous communication channel, and option "LAN" enables a local network between Partners. A special software package needs to be used for the last two options to work.

Our Partner has an I/O card which provides 3 I/O channels. The card itself is named "LAN" and "comes with" a manual called "Communication Adapter LSYN-002". It is not yet clear which of the above extensions are implemented with this card, but most likely it adds options "Lsyn 0002" and "LAN". Looking at this Manual, it becomes apparent that the LPT RS-232 port is labeled as "J8" (and not as "J7") on the back of the computer if this card is installed. So, our best bet is to connect to the "J8" port.

The IDP Manual explains how the ports can be configured. Specifically, there are logical I/O channels (CON, AUX, LST) and physical I/O channels (GDP, CRT, LPT, VAX, MOD, CEN). The CP/M command "DEVICE" can be used to tie a logical channel to a physical channel and also set the communication parameters (such as flow control and baud rate). The command is used as follows: DEVICE logical-channel:=physical-channel[parameters. For example, DEVICE AUX:=LPT[x,1200 ties the logical channel "AUX" to the physical channel "LPT" and sets the flow control to XON/XOFF and baud rate to 1200 bauds per second.

The User's Manual suggests using the "RMT20" program to utilize Partner as a terminal. The manual hints that RMT20 communicates with a remote computer through the AUX logical I/O channel. This led us to connect a [female] DB25 connector to the LPT port, configure the AUX channel, and test if RMT20 transmits something over the transmit line.

To set up the connection, we soldered two wires to the DB25 connector, one to pin 2 (TX, transmit) and the other to pin 7 (GND, ground). We then plugged this connector to "J8" on Partner. Next, we attached an oscilloscope to the two attached wires. We assigned the LPT physical channel to the AUX port and disabled hardware flow control by setting it to XON/XOFF using the CP/M command DEVICE aux:=lpt[x,1200. We found the RMT20 program on the hard disk provided with the emulator (GRMT20.COM). When pressing keys on Partner's keyboard, we were able to detect, with the oscilloscope, that characters were being transmitted over the TX line.

Since our PC did not have a serial port, we had to use a USB-to-Serial adapter. The adapter had a female DB9 connector on one end. We attached the two wires coming from the Partner to a male DB9 connector, with one wire connected to pin 5 (GND, ground) and the other to pin 2 (RX, receive). Next, we attached the USB adapter to the PC and configured a terminal program to match the AUX/LPT settings on the Partner. We discovered that we needed to set the baud rate to twice the setting on the Partner for it to transmit correctly. With this setup, we were able to receive data on the PC.

We ended up creating a full-blown null-modem cable. However, we discovered that the DTR and DSR signals are not supported by IDP, which means that we had to set the PC terminal to RTS/CTS hardware flow control when switching the Partner to "hardware flow control".

After successfully establishing communication, our next step was to be able to do the same thing from within our own program running on the Partner. To get started, we decided to look at how GRMT20 sends a character to the PC. Using the emulator, we were able to trace the program and locate the following piece of code:

We were able to use this code to send a character to the PC, but only after running GRMT20 first and breaking out of it with Shift+Break. This suggested that GRMT20 initializes the Z80 SIO chips that are used by IDP for serial communication. Upon further investigation, we discovered that GRMT20 extends BDOS with SIO-related functions and installs its own interrupt handlers. While this may have been a viable solution, it seemed too messy for our liking, so we decided to refer to the Z80 SIO documentation instead (this or this).

IDP has two SIO chips, each supporting two channels corresponding to CRT, LPT, VAX, and MOD, respectively. We were using channel B on the first SIO chip (LPT), and we had to make sure not to break the keyboard that was using channel A on the same chip. Interestingly, disabling the "Status Affects Vector" option on channel B can actually break the keyboard, since this setting affects both channels. Similarly, setting the interrupt vector also affects both channels and can have the same effect.

By initializing SIO correctly, we were soon able to send a character to the PC. With this accomplished, we moved on to receiving characters and creating a full-blown polling loop. Since interrupts can bring in all sorts of trouble, we decided not to utilize them in the first step. Nonetheless, we explored interrupts to set the groundwork for using them later in the project.

The IDP interrupt vectors for the SIO channels are as follows:

• Chip 1, channel B (LPT): 90h
• Chip 1, channel A (CRT; keyboard): 98h
• Chip 2, channel B: A0h
• Chip 2, channel A: A8h

These addresses are offsets from the start of BIOS. To obtain the BIOS address, we need to read the memory at 0001h and subtract 3 from that. On our Partner, that's FA00h.

Interrupt handlers and the buffers used by the handlers must reside in the shared memory space because they can fire when either of the two memory banks is enabled. The shared memory space supposedly starts at C000h and goes to FFFFh, with BDOS starting at F400h. Further tests are needed to validate this. The space available for handlers is thus from C000h to F400h. However, other interrupt handlers and their data may be installed here, so we must be careful not to overwrite them. The keyboard handler is at FEA7h (inside BIOS, which is good as we will not interfere with it). GRMT installs its SIO handlers at EE9Ch and EE81h (and we most likely should do the same).

When utilizing interrupts, certain functions must be put into "transactions" and not allow the interrupt handlers to execute while they are executing, especially when addressing the SIO registers. We are not yet sure whether this can be achieved simply with DI-EI or whether something more elaborate is required.

As you can see, interrupts pose several challenges. We are not yet sure if these outweigh the benefits. However, we will explore this further as it represents a good challenge and will uncover a lot about how IDP interrupts work.

In conclusion, we were able to establish a successful serial connection between an Iskra Delta Partner and a PC. We were able to configure both the physical and logical I/O channels for initial testing. Despite encountering some hurdles, we managed to implement a serial communication library for IDP. In addition, we delved into the Z80 SIO documentation and gained a deeper understanding of the Partner's serial communication system. Last but not least, we laid the foundation for extending the library with interrupts in the future.

To retrieve the data from the old floppies, we used Kryoflux - a USB-based device designed specifically for acquiring reliable low-level reads suitable for software preservation. With the help of Kryoflux and a standard 80-track floppy drive, specifically, the Newtronics Mitsumi D509V5, we were able to read the magnetic flux transitions on the disk and reconstruct the data in a way that was faithful to the original.

The floppies we worked with had two sides, with 80 tracks per side, 5 sectors per track, and 1024 bytes per sector. Such a configuration would normally denote high-density floppies, but in our case, they were double-density floppies.

Our process of reading the data in the end converged to the following steps:

1. Check the maker of the floppy. Different manufacturers used different magnetic materials and coatings, which could affect the readout quality. For example, if you learn that a certain manufacturer's floppies from the same batch tend to disintegrate in the drive, you might want to avoid reading them entirely. Similarly, if you notice that a read heavily changes the magnetic disk by leaving scratches or marks, you might want to leave those disks for the end of the process, because that will also smear the drive heads and you will need to clean them.

2. Inspect the magnetic disk visually. Look for any signs of damage, such as scratches, mold, or dust. This is important because you want to remember the state the disk is in so you can see if the read visibly damages the disk. Furthermore, if you notice dust on the disk, gently blow it off before inserting the floppy into the drive. If you notice mold on the disk, clean it gently with a cotton swab and isopropyl alcohol, being careful not to damage the magnetic surface of the disk. If you notice heavy scratches, just be aware of them, as there isn't much you can do to repair the damage.

3. Insert the floppy and note the sounds coming out of the drive, such as clicking, grinding, or squealing. These sounds usually appear immediately after closing the drive door as the drive spins up. If you hear any worrying sounds, it's important to take caution. It may be best to do a partial read instead, then abort and check what happened to the disk before proceeding with a full read. You might want to read such floppies at the end, or if there is no visible damage, proceed with reading them anyway.

4. Read the floppy using Kryoflux. This involves connecting the floppy drive to the Kryoflux device and running the appropriate software to extract the data from the disk. You can choose to do either a full or partial read. A full read involves reading every track on the disk, while a partial read involves only reading specific tracks. We will talk more about this step later on.

5. Inspect the magnetic disk visually again. Look for any new signs of damage that may have occurred during the readout process. By checking for any new signs of damage, you can determine whether you can simply re-read the floppy to retrieve more good sectors. If the condition of the disk did not change, this is possible. However, if the disk deteriorated during the readout process, you should be careful with your next read and only attempt to read the missing tracks. If the disk disintegrated completely, there is nothing you can do, and subsequent reads will be in vain. In such cases, you need to clean the drive heads, as the material that fell off the disk is most likely on the drive heads.

6. Check the retrieved data. After the data has been retrieved from the floppy, it is important to check the integrity of the data. One way to do this is to use the HxC Floppy Emulator software to decode the data and identify any bad sectors with incorrect CRC codes. This information can be used to determine which tracks need to be re-read or where on the magnetic disk an issue may be located. Another tool that can be used to check the state of the data is the Kryoflux Disk Tool Console (DTC) software. This software can identify which tracks contain bad sectors. This information is crucial for attempting to fix issues, re-read data, and/or reconstruct the data. We will talk more about this later on in this post.

7. Clean the drive heads if necessary. When reading deteriorated floppy disks, there is a chance that material from the magnetic disk has ended up on the drive heads, which can not only prevent the drive from reading subsequent floppies, but can also damage them. If you notice that the read has caused heavy deterioration of the disk, it's important to clean the drive heads carefully. However, cleaning the heads can be a delicate process, and if done incorrectly, it can render your drive useless. To clean the heads, you can start by gently blowing towards the drive heads. If you still see black specks on the heads, you can use a flattened cotton swab with isopropyl to gently clean the heads by barely touching them, being careful not to lift the upper head.

8. Repeat the read if necessary. After completing the read of the floppy and examining the retrieved data, you may find that there are still some bad sectors that were not successfully read. In this case, it may be necessary to repeat the read. However, it's important to note that repeated reads can further damage the magnetic disk, so you should only do so if you believe it's necessary and the disk is still in good enough condition. It's generally best to re-read only the tracks that were not successfully read, rather than re-reading the entire disk. Once you have successfully read all the necessary tracks, you can then combine the data from each read into a full image of the floppy.

In the following section, we provide more details on how we used the Kryoflux and HxC software for reading and decoding our floppies.

Reading with Kryoflux DTC. Kryoflux's DTC (Disk Tool Console) is a tool for reading and writing floppy disks. To read a floppy disk, we used the following command in the Windows console:

dtc -d1 -ffloppy_name\floppy_name_ -i0

Here, -d1 specifies the drive number, floppy_name is the name of the floppy disk we want to read, and -i0 specifies that we want to perform a low-level read for archival purposes. Please refer to the DTC Manual for more information.

Checking for Successful Read. After reading the floppy disk, we needed to check whether the read was successful. To do this, we issued the following command:

dtc -m1 -ffloppy_name\* -i0 -ftest.img -z3 -i4 2>&1 | findstr "failed mismatch unformatted"

The following explains the parameters that we used. Once again, please refer to the DTC Manual for more information.

• -m1: Enables the image file input.
• -ffloppy_name\*: Specifies the image files to read.
• -i0: Specifies the format of the input image file.
• -ftest.img: Specifies the output file for the decoded image.
• -z3: Specifies the sector size (in this case, 1024 bytes).
• -i4: Specifies the format of the output image file (MFM, 80 tracks).
• 2>&1: Redirects error messages to standard output so they can be piped to the next command.
• |: Pipes the output of the DTC command to the "findstr" command.
• findstr "failed mismatch unformatted": Searches the output for the strings "failed", "mismatch", and "unformatted", and displays any lines that contain them. This is used to determine which tracks, if any, had errors during the read process.

If the read was not completely successful, the above command will expose any bad tracks that may have been encountered during the read process. For example:

44.0    : Read operation failed
45.0    : Read operation failed
80.0    : MFM: <unformatted>
80.1    : MFM: <unformatted>
81.0    : MFM: <unformatted>
81.1    : MFM: <unformatted>
82.0    : MFM: <mismatch>, *NT
82.1    : MFM: <unformatted>
83.0    : MFM: <unformatted>
83.1    : MFM: <unformatted>

In the above example, tracks 44 and 45 (on side 0) were not read successfully, and tracks 80 to 83 were either unformatted or had a mismatch. However, note that unformatted and mismatched tracks after track 79 (which is the 80th consecutive track) are usually not a cause for concern on an 80-track floppy disk.

Given the above, we should re-read tracks 44 and 45 to ensure that the data is fully recovered. When re-reading, it is important to use DTC's options -g, -s, and -e to properly target the bad tracks. The -g option allows DTC to read only one side of the disk. The -s option specifies the start track to read, and the -e option specifies the end track to read. By specifying the range of affected tracks, DTC can focus on recovering only the necessary data, reducing the risk of further damaging the disk.

If we have created multiple images of a floppy disk using the Kryoflux DTC software, the next step is to combine the resulting tracks. This can be done simply by copying the corresponding track files into the same folder.

Another software we used to check the success of our reads is the HxC Floppy Emulator software. This software allows us to visualize and analyze the data acquired with Kryoflux. The visualizations provided by the HxC software are especially helpful in showing the location of damaged areas on the disk. We can then visually inspect the damaged area to see if it can be cleaned or fixed in some other way.

Moreover, the HxC software provides detailed information about the exact location of the damaged sectors. This information can be useful for reconstructing tracks from sectors, a process that can be challenging but is achievable with the help of specialized tools.

In Conclusion... We have outlined the process we used to quite successfully read and decode 30-40 years old floppy disks. By using the Kryoflux DTC software, we were able to read and assess the quality of the data, and then by using the HxC software, we were able to analyze and visualize the data to determine its integrity.

We want to emphasize that the methodology we presented here is not intended as a recommendation, but rather as a record of what worked for us in our specific case. The process of reading and decoding old floppy disks can be complex and challenging, and the results will vary depending on the condition of the disks and other factors.

If you are attempting to recover data from old floppy disks, we recommend that you carefully research the available methods and tools, and consult with experts if necessary. With patience, persistence, and a bit of luck, it is often possible to recover valuable data from these seemingly unsalvageable storage media.

Resources

These Kryoflux floppy images are available here:

• https://files.oddbit-retro.org/pub/GorenjeDialog/FloppyImg/DialogDisketeBox1.zip
• https://files.oddbit-retro.org/pub/GorenjeDialog/FloppyImg/DialogDisketeBox2.zip