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.
Understand and extend
start(Api)uses the Microsoft x64 ABI. The startup object negotiates API/runtime requirements before calling it.gfx_initandinput_initset up header wrappers; they do not create an operating-system window.input_pollrefreshes state. Held keys move continuously; Escape uses an edge event to exit.- The program redraws its back buffer and calls
gfx_presentonce 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.