Integrating Free API into your application

# Inside your game repository
git submodule add https://github.com/openeggbert/free-api.git external/free-api
git submodule update --init --recursive
      

cmake_minimum_required(VERSION 3.23)
project(MyGame CXX)

# SDL3 must be available before free-api is added.
# If using the free-eggbert vendored SDL, include ThirdPartySDL.cmake first.
# Otherwise install SDL3 via your package manager.
find_package(SDL3 REQUIRED)
find_package(SDL3_image REQUIRED)
find_package(SDL3_mixer REQUIRED)

# Disable tests when embedding free-api
set(FREE_API_BUILD_TESTS OFF CACHE BOOL "" FORCE)
add_subdirectory(external/free-api)

add_executable(MyGame
    src/main.cpp
    # ... your source files
)

set_target_properties(MyGame PROPERTIES
    CXX_STANDARD 20
    CXX_STANDARD_REQUIRED YES
)

target_link_libraries(MyGame PRIVATE
    free-api::free-api          # the library itself
    free-api::compat_headers    # drop-in windows.h, io.h, etc.
)
      

#include <windows.h>

// Generates a standard main() that calls WinMain.
// Only active on non-Windows platforms.
FREE_API_IMPLEMENT_WINMAIN()
{
    // Original WinMain body
    WNDCLASSA wc = {};
    wc.lpfnWndProc   = MyWindowProc;
    wc.hInstance     = hInstance;
    wc.lpszClassName = "MyGameClass";
    RegisterClass(&wc);

    HWND hwnd = CreateWindowA(
        "MyGameClass", "My Game",
        WS_OVERLAPPEDWINDOW, 100, 100, 800, 600,
        NULL, NULL, hInstance, NULL);
    ShowWindow(hwnd, SW_SHOW);

    MSG msg;
    while (GetMessage(&msg, NULL, 0, 0)) {
        TranslateMessage(&msg);
        DispatchMessage(&msg);
    }
    return (int)msg.wParam;
}
      

#include <windows.h>

// Forward-declare WinMain from the game's original source
int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int);

int main(int argc, char** argv)
{
    return FreeApiRunWinMain(&WinMain, argc, argv);
}
      

LRESULT CALLBACK MyWindowProc(HWND hWnd, UINT uMsg, WPARAM wParam, LPARAM lParam)
{
    switch (uMsg) {

    case WM_CREATE:
        // Window was just created; initialise game state here
        return 0;

    case WM_DESTROY:
        PostQuitMessage(0);
        return 0;

    case WM_KEYDOWN:
        switch (wParam) {
        case VK_ESCAPE:  PostQuitMessage(0); break;
        case VK_LEFT:    /* move player left */ break;
        case VK_RIGHT:   /* move player right */ break;
        case VK_SPACE:   /* fire */ break;
        }
        return 0;

    case WM_MOUSEMOVE: {
        int x = LOWORD(lParam);  // cursor X in client coords
        int y = HIWORD(lParam);  // cursor Y in client coords
        // BOOL lBtn = (wParam & MK_LBUTTON) != 0;
        return 0;
    }

    case WM_LBUTTONDOWN:
        /* handle left click */
        return 0;

    case WM_TIMER:
        /* periodic WM_TIMER from SetTimer */
        return 0;

    }
    return DefWindowProcA(hWnd, uMsg, wParam, lParam);
}
      

// Load a BMP file from disk
HBITMAP hBmp = (HBITMAP)LoadImageA(
    NULL, "data/sprites.bmp",
    IMAGE_BITMAP, 0, 0, LR_LOADFROMFILE);

// Create a memory DC and select the bitmap into it
HDC hdcMem = CreateCompatibleDC(NULL);
HGDIOBJ hOld = SelectObject(hdcMem, hBmp);

// Get a surface DC for the window (returned by the game engine internals)
// In Free API, the window DC is obtained through the message pump.
// A common pattern is to keep a global HDC set up during WM_CREATE.
HDC hdcWindow = GetWindowDC(hWnd);  // if available in your integration

// Blit: copy 64×64 sprite at (srcX, srcY) to window at (dstX, dstY)
StretchBlt(
    hdcWindow, dstX, dstY, 64, 64,
    hdcMem,    srcX, srcY, 64, 64,
    SRCCOPY);

// Cleanup
SelectObject(hdcMem, hOld);
DeleteDC(hdcMem);
DeleteObject(hBmp);
      

// Read a pixel colour from a memory DC
COLORREF col = GetPixel(hdcMem, x, y);
BYTE r = GetRValue(col);
BYTE g = GetGValue(col);
BYTE b = GetBValue(col);

// Write a pixel
SetPixel(hdcMem, x, y, RGB(255, 0, 0));  // bright red
      

#include <windows.h>
#include <mmsystem.h>

MCIDEVICEID g_mciDevice = 0;

void PlayMusic(const char* midiPath, HWND hWndNotify)
{
    // Close any currently open device
    if (g_mciDevice) {
        mciSendCommand(g_mciDevice, MCI_CLOSE, 0, 0);
        g_mciDevice = 0;
    }

    MCI_OPEN_PARMS op = {};
    op.lpstrDeviceType  = "sequencer";
    op.lpstrElementName = midiPath;

    MCIERROR err = mciSendCommand(0, MCI_OPEN,
        MCI_OPEN_TYPE | MCI_OPEN_ELEMENT,
        (DWORD_PTR)&op);

    if (err != MMSYSERR_NOERROR) {
        char msg[128];
        mciGetErrorString(err, msg, sizeof(msg));
        OutputDebugString(msg);
        return;
    }

    g_mciDevice = op.wDeviceID;

    MCI_PLAY_PARMS pp = {};
    pp.dwCallback = (DWORD_PTR)hWndNotify;  // window to receive MM_MCINOTIFY

    mciSendCommand(g_mciDevice, MCI_PLAY, MCI_NOTIFY, (DWORD_PTR)&pp);
}

void StopMusic()
{
    if (g_mciDevice) {
        mciSendCommand(g_mciDevice, MCI_CLOSE, 0, 0);
        g_mciDevice = 0;
    }
}
      

case MM_MCINOTIFY:
    if (wParam == MCI_NOTIFY_SUCCESSFUL) {
        // Song finished — loop or play next track
        PlayMusic("data/music/level2.mid", hWnd);
    }
    return 0;
      

// Open a dummy MIDI output handle
HMIDIOUT hmo;
midiOutOpen(&hmo, MIDI_MAPPER, 0, 0, 0);

// Set volume: high word = right channel, low word = left channel (0–0xFFFF)
DWORD vol = 0xC000C000;  // ~75% volume both channels
midiOutSetVolume(hmo, vol);

midiOutClose(hmo);
      

#include <windows.h>
#include <mmsystem.h>

UINT g_timerId = 0;

void CALLBACK TimerProc(UINT uTimerID, UINT uMsg,
                         DWORD_PTR dwUser, DWORD_PTR dw1, DWORD_PTR dw2)
{
    HWND hWnd = (HWND)dwUser;
    // Post a custom update message to the main window
    PostMessage(hWnd, WM_USER + 1, 0, 0);
}

void StartGameTimer(HWND hWnd)
{
    // Fire every 50 ms (20 Hz), 1 ms resolution
    g_timerId = timeSetEvent(50, 1, TimerProc, (DWORD_PTR)hWnd, TIME_PERIODIC);
}

void StopGameTimer()
{
    if (g_timerId) {
        timeKillEvent(g_timerId);
        g_timerId = 0;
    }
}
      

// All of these are handled by the fopen wrapper:
FILE* f1 = fopen("data\\config.def", "r");       // backslash → slash
FILE* f2 = fopen("C:\\game\\data\\map.dat", "rb"); // drive + backslash → relative
FILE* f3 = fopen("DATA\\LEVEL01.BLP", "rb");      // uppercase fallback
      

// Creates the directory; backslashes and drive letters are handled
CreateDirectoryA("savegames", NULL);
CreateDirectoryA("C:\\MyGame\\saves", NULL);  // becomes "MyGame/saves" relative
      

#include <io.h>

struct _finddata_t fd;
intptr_t handle = _findfirst("levels\\*.blp", &fd);
if (handle != -1) {
    do {
        printf("Found: %s\n", fd.name);
    } while (_findnext(handle, &fd) == 0);
    _findclose(handle);
}
      

cmake -B build -DFREE_API_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failure
      

FREE_API_DEBUG_INPUT=1 ./MyGame

FREE_API_DEBUG_MIDI=1 ./MyGame

FREE_API_SOUNDFONT=/usr/share/sounds/sf2/FluidR3_GM.sf2 ./MyGame

#include <windows.h>
#include <mmsystem.h>

static HWND      g_hWnd      = NULL;
static HDC       g_hdcMem   = NULL;
static HBITMAP   g_hBmp     = NULL;
static MCIDEVICEID g_music  = 0;

void Render()
{
    if (!g_hdcMem || !g_hBmp) return;

    RECT rc; GetClientRect(g_hWnd, &rc);
    HDC hdcWin = (HDC)GetWindowDC(g_hWnd); // game-specific DC

    StretchBlt(hdcWin, 0, 0, rc.right, rc.bottom,
               g_hdcMem, 0, 0, 320, 200, SRCCOPY);
}

LRESULT CALLBACK WndProc(HWND hWnd, UINT msg, WPARAM wp, LPARAM lp)
{
    switch (msg) {
    case WM_CREATE:
        g_hBmp  = (HBITMAP)LoadImageA(NULL, "data/title.bmp",
                      IMAGE_BITMAP, 0, 0, LR_LOADFROMFILE);
        g_hdcMem = CreateCompatibleDC(NULL);
        SelectObject(g_hdcMem, g_hBmp);
        {
            MCI_OPEN_PARMS op = {};
            op.lpstrDeviceType  = "sequencer";
            op.lpstrElementName = "data/music/theme.mid";
            if (!mciSendCommand(0, MCI_OPEN,
                    MCI_OPEN_TYPE | MCI_OPEN_ELEMENT, (DWORD_PTR)&op)) {
                g_music = op.wDeviceID;
                MCI_PLAY_PARMS pp = { (DWORD_PTR)hWnd };
                mciSendCommand(g_music, MCI_PLAY, MCI_NOTIFY, (DWORD_PTR)&pp);
            }
        }
        return 0;

    case WM_DESTROY:
        if (g_music) mciSendCommand(g_music, MCI_CLOSE, 0, 0);
        if (g_hdcMem) DeleteDC(g_hdcMem);
        if (g_hBmp)   DeleteObject(g_hBmp);
        PostQuitMessage(0);
        return 0;

    case WM_KEYDOWN:
        if (wp == VK_ESCAPE) DestroyWindow(hWnd);
        return 0;

    case MM_MCINOTIFY:
        if (wp == MCI_NOTIFY_SUCCESSFUL && g_music) {
            MCI_PLAY_PARMS pp = { (DWORD_PTR)hWnd };
            mciSendCommand(g_music, MCI_PLAY, MCI_NOTIFY, (DWORD_PTR)&pp);
        }
        return 0;
    }
    return DefWindowProcA(hWnd, msg, wp, lp);
}

FREE_API_IMPLEMENT_WINMAIN()
{
    WNDCLASSA wc = {};
    wc.lpfnWndProc   = WndProc;
    wc.hInstance     = hInstance;
    wc.lpszClassName = "GameWindow";
    RegisterClass(&wc);

    g_hWnd = CreateWindowA(
        "GameWindow", "My Game",
        WS_OVERLAPPEDWINDOW, 100, 100, 800, 600,
        NULL, NULL, hInstance, NULL);
    ShowWindow(g_hWnd, SW_SHOW);

    MSG msg;
    while (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) {
        if (msg.message == WM_QUIT) break;
        TranslateMessage(&msg);
        DispatchMessage(&msg);
        Render();
    }
    return (int)msg.wParam;
}