minwindef.h · windef.h · winnt.h

Types & Handles

Fundamental Win32 scalar types, opaque handle types, calling-convention macros, and pointer-width integers. These are the building blocks used by every other part of the API.

minwindef.h

Scalar types

Win32 defines its own set of type aliases so that the same code compiles unchanged on 16-bit, 32-bit, and 64-bit targets. Free API mirrors them exactly.

Type	Underlying type	Status	Notes
`BOOL`	`int`	HEADER_ONLY	Win32 boolean. Use `TRUE` / `FALSE` macros (1 / 0). Functions may return any non-zero value for TRUE.
`BYTE`	`unsigned char`	HEADER_ONLY	8-bit unsigned.
`WORD`	`unsigned short`	HEADER_ONLY	16-bit unsigned.
`DWORD`	`unsigned long`	HEADER_ONLY	32-bit unsigned. Used extensively for flags, lengths, and IDs.
`UINT`	`unsigned int`	HEADER_ONLY	Platform-width unsigned integer.
`INT`	`int`	HEADER_ONLY	Platform-width signed integer.
`LONG`	`long`	HEADER_ONLY	Always 32-bit on Windows; may be 64-bit on LP64 Linux — use `LONG` only for Win32 struct compatibility.
`FLOAT`	`float`	HEADER_ONLY	Single-precision float alias.
`TRUE` / `FALSE`	macro (1 / 0)	HEADER_ONLY	Standard BOOL values.
`MAX_PATH`	macro (260)	HEADER_ONLY	Maximum path length in characters. POSIX `PATH_MAX` may differ but 260 is safe for file names passed to Free API.

String / buffer pointer types

Type	Underlying type	Notes
`LPSTR`	`char*`	Pointer to mutable ANSI string.
`LPCSTR`	`const char*`	Pointer to constant ANSI string. Most Free API functions accept LPCSTR for path/name arguments.
`LPWSTR`	`wchar_t*`	Wide string — declared but not used by Free API (no Unicode implementation).
`LPCWSTR`	`const wchar_t*`	Wide constant string — declared for compilation only.
`LPVOID`	`void*`	Generic pointer.
`LPCVOID`	`const void*`	Pointer to read-only memory.
`LPBYTE`	`BYTE*`	Byte buffer pointer.

Geometry types

Type	Fields	Notes
`RECT` / `LPRECT`	`LONG left, top, right, bottom`	Axis-aligned rectangle. Used by `GetClientRect`, `IntersectRect`, etc.
`POINT` / `LPPOINT`	`LONG x, y`	Screen or client coordinates. Used by `GetCursorPos`, `ClientToScreen`, etc.
`SIZE`	`LONG cx, cy`	Width/height pair.

C++ — typical usage of scalar types

#include <windows.h>

// DWORD for counts, flags, and IDs
DWORD flags = MCI_OPEN_TYPE | MCI_OPEN_ELEMENT;
DWORD tick  = GetTickCount();

// BOOL return values — test with != FALSE, not == TRUE
BOOL ok = CreateDirectoryA("saves", NULL);
if (ok != FALSE) { /* directory created */ }

// RECT filled by the API
RECT rc;
GetClientRect(hwnd, &rc);
int width  = rc.right  - rc.left;
int height = rc.bottom - rc.top;

// POINT for cursor position
POINT pt;
GetCursorPos(&pt);          // screen coords
ScreenToClient(hwnd, &pt);  // convert to window-client coords

windef.h

Opaque handle types

Win32 uses opaque handles to refer to kernel objects. Free API maps each handle type to an internal registry entry backed by SDL3 objects.

Type	Free API backing	Status	Notes
`HWND`	Internal window registry (SDL windowID)	PARTIAL	Returned by `CreateWindowExA`. Maps to exactly one SDL window. Valid until `DestroyWindow` is called. `HWND_DESKTOP` is defined as `((HWND)0)`.
`HDC`	Internal DC record (pointer to SDL surface)	PARTIAL	Either a memory DC (`CreateCompatibleDC`) or a surface DC. Only SRCCOPY blitting between these two types is implemented.
`HBITMAP`	SDL3 surface (RGBA32)	PARTIAL	Returned by `LoadImageA` and `CreateBitmap`. Must be freed with `DeleteObject`.
`HGDIOBJ`	Generic GDI handle (HBITMAP or other)	PARTIAL	Used as parameter/return type of `SelectObject` and `DeleteObject`. Cast freely between `HBITMAP` and `HGDIOBJ`.
`HINSTANCE` / `HMODULE`	NULL	STUB	Always NULL. Target games pass it to `CreateWindowExA` / `RegisterClassA` where it is ignored by Free API.
`HMENU`	NULL	STUB	Menus are not implemented. Pass NULL wherever HMENU is needed.
`HICON` / `HCURSOR`	NULL	STUB	`LoadIconA` and `LoadCursorA` return NULL. Games that test the result before use will not crash.
`HBRUSH`	NULL	STUB	Background brush in `WNDCLASSA.hbrBackground` is stored but not used during window painting.
`HANDLE`	Generic opaque handle	PARTIAL	Base handle type. Alias for `void*`. Used by `LoadImageA` return type.
`HRSRC` / `HGLOBAL`	NULL	STUB	Win32 resource handles. All resource functions (`FindResourceA`, `LoadResource`…) are stubs.
`ATOM`	`typedef WORD`	HEADER_ONLY	Returned by `RegisterClassA`. Free API always returns 1 (non-zero = success).

C++ — handle lifecycle example

// Window handle — create → use → destroy
HWND hwnd = CreateWindowA("MyClass", "Title",
    WS_OVERLAPPEDWINDOW, 100, 100, 800, 600,
    NULL, NULL, NULL, NULL);

// Bitmap handle — load → select into DC → use → cleanup
HBITMAP hBmp = (HBITMAP)LoadImageA(
    NULL, "assets/sprites.bmp",
    IMAGE_BITMAP, 0, 0, LR_LOADFROMFILE);

HDC hdcMem  = CreateCompatibleDC(NULL);
HGDIOBJ old = SelectObject(hdcMem, hBmp);

// ... use hdcMem for blitting ...

// Always restore and clean up
SelectObject(hdcMem, old);
DeleteDC(hdcMem);
DeleteObject(hBmp);

windef.h

Calling conventions & pointer-width integers

Macro / Type	On non-MSVC	Purpose
`WINAPI`	expands to nothing	Standard Win32 calling convention. Applied to all API function declarations.
`WINAPIV`	expands to nothing	Variadic variant (e.g. `wsprintfA`).
`CALLBACK`	expands to nothing	Marks user-supplied callbacks (WNDPROC, LPTIMECALLBACK).
`WPARAM`	`uintptr_t`	Unsigned pointer-width; first message parameter.
`LPARAM`	`intptr_t`	Signed pointer-width; second message parameter. Mouse coordinates packed as `(y<<16)\|x`.
`LRESULT`	`intptr_t`	Return value of WNDPROC and DispatchMessageA.
`DWORD_PTR`	`uintptr_t`	DWORD stretched to pointer width. Used by MCI callback parameters.
`UINT_PTR`	`uintptr_t`	UINT stretched to pointer width. Used by timer IDs.
`LONG_PTR`	`intptr_t`	LONG stretched to pointer width.
`ULONG_PTR`	`uintptr_t`	ULONG stretched to pointer width.

lParam mouse coordinate packing Mouse messages encode cursor position as lParam = (y << 16) | (x & 0xFFFF). Extract with the standard macros: int x = LOWORD(lParam); and int y = HIWORD(lParam); (both defined in minwindef.h).

winnt.h

String types, HRESULT & COM basics

Symbol	Underlying type	Status	Notes
`CHAR`	`char`	HEADER_ONLY	ANSI character.
`WCHAR`	`wchar_t`	HEADER_ONLY	Wide character. Unicode APIs not implemented.
`TCHAR`	`char` (ANSI build)	HEADER_ONLY	Resolves to CHAR when UNICODE is not defined (default for Free API).
`HRESULT`	`long`	HEADER_ONLY	COM result code. Negative = error, zero or positive = success.
`S_OK`	0x00000000	HEADER_ONLY	COM success.
`S_FALSE`	0x00000001	HEADER_ONLY	COM success with alternate result.
`E_FAIL`	0x80004005	HEADER_ONLY	Generic COM failure.
`GUID`	struct {Data1,Data2,Data3,Data4}	HEADER_ONLY	128-bit globally unique identifier. Declared for compilation compatibility.

C++ — HRESULT pattern

// HRESULT success test — use SUCCEEDED/FAILED macros
HRESULT hr = SomeComFunction();
if (SUCCEEDED(hr)) {
    // ok — hr is S_OK (0) or S_FALSE (1)
} else {
    // error — hr has a negative value like E_FAIL
}

// Equivalent manual test
if (hr >= 0) { /* success */ }