bMETAL / DOS64

SDK / Guided example

Your first graphical app

Draw a colored panel, move a square with the arrow keys, and press Escape to exit. Build one freestanding PE executable and run it unchanged in DOS64 or on Windows with bmetal.dll.

This walkthrough uses the standalone API 14 SDK, not the older SDK files inside the disk image. You need an x86-64 MinGW-w64 GCC toolchain; the compiler is not included in the ZIP.

Prepare the SDK

Download and extract the standalone SDK into a working directory. Work from that directory so the relative paths below resolve:

include/dos64_*.h
lib/dos64_startup.o
lib/libbmetal.dll.a
bin/bmetal.dll
hello.c
startup.c

On Debian/Ubuntu, the cross-compiler package is gcc-mingw-w64-x86-64. On Windows, use an x86-64 MinGW-w64 environment such as the MSYS2 UCRT64 shell with its GCC toolchain installed. The Windows compiler command may be gcc instead of x86_64-w64-mingw32-gcc.

Keep the original hello example. Create a separate file named firstgfx.c for this application.

Write the application

Copy this complete application into firstgfx.c. The SDK startup object supplies the entry adapter; do not define another dos64_entry function.

#include <dos64_gfx.h>
#include <dos64_input.h>

int __attribute__((ms_abi)) start(const DOS64_API *Api)
{
    gfx_init(Api);
    input_init(Api);

    int Width = gfx_width();
    int Height = gfx_height();
    if (Width < 320 || Height < 200) {
        Api->Write("FIRSTGFX: display must be at least 320x200\n");
        return 1;
    }

    int X = Width / 2 - 16;
    int Y = Height / 2 - 16;
    for (;;) {
        input_poll();
        if (key_pressed(KEY_ESC)) { break; }

        X += (key_down(KEY_RIGHT) - key_down(KEY_LEFT)) * 4;
        Y += (key_down(KEY_DOWN) - key_down(KEY_UP)) * 4;
        if (X < 16) { X = 16; }
        if (X > Width - 48) { X = Width - 48; }
        if (Y < 80) { Y = 80; }
        if (Y > Height - 48) { Y = Height - 48; }

        gfx_clear(GFX_COLOR_ARGB(255, 17, 21, 34));
        gfx_set_color(GFX_COLOR_ARGB(255, 35, 43, 62));
        gfx_fill_rect(8, 72, Width - 16, Height - 80);
        gfx_draw_text(16, 16, "My first DOS64 app",
                      GFX_CYAN, GFX_TRANSPARENT);
        gfx_draw_text(16, 40, "Arrows: move / Esc: exit",
                      GFX_WHITE, GFX_TRANSPARENT);
        gfx_set_color(GFX_COLOR_ARGB(255, 189, 155, 255));
        gfx_fill_rect(X, Y, 32, 32);
        gfx_present();
        Api->Sleep(16);
    }

    Api->Write("FIRSTGFX: finished\n");
    return 0;
}

Compile the executable

On Linux, run this from the extracted SDK directory. It links only the SDK startup object and runtime import library, without the host CRT or libc:

x86_64-w64-mingw32-gcc -m64 -O2 -Wall -Wextra -Werror \
  -ffreestanding -nostdlib -nostartfiles -fno-stack-protector -mno-red-zone \
  -Iinclude -Wl,-e,dos64_entry -Wl,--subsystem,windows -Wl,--dynamicbase \
  firstgfx.c lib/dos64_startup.o -Llib -lbmetal -o bin/firstgfx.exe

In a Windows MinGW-w64 shell, use the same command with the installed compiler name, usually gcc. The backslash continuations above are shell syntax for Linux/MSYS2; for PowerShell or Command Prompt, paste it as one line.

--subsystem,windows selects a graphical Windows application. It does not change the DOS64 API or remove DOS64 compatibility. Expected result: bin/firstgfx.exe, with no compiler diagnostics.

Run on Windows

Copy the entire bin directory to an x86-64 Windows machine, or use the directory already built there. Ensure these files are together:

bin/
  firstgfx.exe
  bmetal.dll

Launch firstgfx.exe, or run .\bin\firstgfx.exe from PowerShell in the SDK directory. Expect a dark window with instructions and a lavender square. Focus the window, hold an arrow key to move, and press Escape to close.

A missing-DLL error means bmetal.dll is not beside the executable or is incompatible. A runtime-negotiation diagnostic means the DLL cannot provide the requested API/services; use the matching SDK runtime rather than bypassing negotiation.

Run in DOS64

Copy bin/firstgfx.exe onto the image's C: volume while its VM is fully stopped. You can use a FAT-capable image tool. For the currently published IMG, this Linux command copies to the root of C: without mounting:

mcopy -i /path/to/bmetal-dos64-usb.img@@53477376 \
  bin/firstgfx.exe ::/FIRSTGFX.EXE

This changes your local image. Back it up first. The offset 53,477,376 bytes is specific to the C: partition in the current download; do not reuse it for another disk layout. Never modify an image being used by QEMU. The checksum will differ after adding a file.

Boot using the QEMU instructions, then enter:

C:\FIRSTGFX.EXE

The same interface should appear on the DOS64 framebuffer. Test arrow movement and Escape; the shell should return and log FIRSTGFX: finished. No Windows DLL is needed in DOS64: the kernel resolves the supported runtime imports. No recompilation is required between Windows and DOS64.

Test safely: DOS64 programs run in ring 0 without isolation. Use a disposable VM image first, not a physical disk containing important data.

Understand and extend

  • start(Api) uses the Microsoft x64 ABI. The startup object negotiates API/runtime requirements before calling it.
  • gfx_init and input_init set up header wrappers; they do not create an operating-system window.
  • input_poll refreshes state. Held keys move continuously; Escape uses an edge event to exit.
  • The program redraws its back buffer and calls gfx_present once per frame. Colors are straight-alpha ARGB.
  • Sleep(16) paces the loop and services input. Movement is per frame for simplicity, not a fixed real-time velocity.
  • No files, layers, threads, or audio resources are owned by this example, so returning after the loop needs no extra cleanup.

If there is no movement on Windows, first focus the graphics window. In DOS64, verify the VM has a supported keyboard. If you see a blank frame, check that gfx_present remains in the loop. Link errors mentioning Dos64Run or dos64_entry indicate missing import-library or startup-object arguments.

Next, use monotonic timing for time-based motion, add layers, or try file access. For an ELF build of the same application source, follow the Linux ELF instructions and omit the PE startup/import library.