SDL2 window with hardware-accelerated renderer: a reliable setup guide

The problem you hit first

You call SDL_CreateRenderer with SDL_RENDERER_ACCELERATED, the window opens, but you get a silent software fallback, tearing, or a frozen "not responding" window on macOS or Windows. The useful takeaway: SDL2 initialization, window creation, renderer creation, event pumping, and cleanup form an ordered contract. Break the order or skip event polling and the renderer appears to work while the OS considers the app hung.

Desired outcome

A minimal SDL2 program that initializes the video subsystem, creates a resizable window, obtains a hardware-accelerated 2D renderer with vsync, clears the frame to a solid color, presents it, and exits cleanly on SDL_QUIT. The program should also report whether acceleration and vsync were actually granted.

Prerequisites

A C or C++ compiler for your target platform, plus the SDL2 development headers and libraries. On Linux, pkg-config sdl2 provides compiler and linker flags. On Windows, link against SDL2.lib and SDL2main.lib and add the SDL2 include directory. On macOS and iOS, window creation and the event loop must run on the main thread; SDL2main handles the entry-point requirement on Windows and macOS.

Confirm the major version you target. SDL2 and SDL3 are not drop-in compatible: SDL3 renames and restructures these APIs (for example, SDL_Init returns a result code and event constants changed). The signatures below are SDL2.

Focused procedure

Initialize video

Run this on the main thread. SDL_Init returns 0 on success; on failure, SDL_GetError gives the reason.

if (SDL_Init(SDL_INIT_VIDEO) != 0) {
    /* handle SDL_GetError() */
}

SDL_INIT_VIDEO enables the window and rendering subsystems without pulling in audio or joystick.

Create the window

Choose flags that match your intent. SDL_WINDOW_RESIZABLE allows resizing. SDL_WINDOW_ALLOW_HIGHDPI lets the OS provide high-DPI backing on platforms that support it; behavior varies by platform and SDL minor version.

SDL_Window *win = SDL_CreateWindow("SDL2 Renderer",
    SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED,
    1280, 720, SDL_WINDOW_RESIZABLE);

If win is NULL, call SDL_GetError for the platform-specific reason.

Create an accelerated renderer

Request acceleration and present vsync. SDL_RENDERER_ACCELERATED asks for GPU-backed rendering; SDL_RENDERER_PRESENTVSYNC synchronizes SDL_RenderPresent to the display refresh, avoiding tearing and unbounded frame loops.

SDL_Renderer *ren = SDL_CreateRenderer(win, -1,
    SDL_RENDERER_ACCELERATED | SDL_RENDERER_PRESENTVSYNC);

The -1 lets SDL choose the best driver. If creation fails, fall back to software explicitly rather than silently continuing.

Event loop and present

Pump events every frame. Failing to poll SDL_PollEvent makes the window appear frozen on Windows and macOS even if rendering succeeds.

SDL_Event e;
int running = 1;
while (running) {
    while (SDL_PollEvent(&e)) {
        if (e.type == SDL_QUIT) running = 0;
    }
    SDL_SetRenderDrawColor(ren, 30, 30, 40, 255);
    SDL_RenderClear(ren);
    /* draw calls here */
    SDL_RenderPresent(ren);
}

SDL_RenderClear fills the target with the draw color; SDL_RenderPresent swaps buffers.

Cleanup in order

Destroy the renderer before the window, then quit SDL. Reversing the order can leak GPU resources or crash on some drivers at process exit.

SDL_DestroyRenderer(ren);
SDL_DestroyWindow(win);
SDL_Quit();

Expected checks

Compile and link in a terminal on Linux:

gcc main.c -o sdl_demo $(pkg-config --cflags --libs sdl2)

Run the binary. Success is a window that opens, shows a solid color, and closes cleanly via the close button.

Verify the linked SDL version at runtime to catch header/library mismatches:

SDL_version linked, compiled;
SDL_GetVersion(&linked);
SDL_VERSION(&compiled);

Compare linked.major/minor/patch against compiled.

Inspect actual renderer capabilities:

SDL_RendererInfo info;
SDL_GetRendererInfo(ren, &info);

Check info.flags for SDL_RENDERER_ACCELERATED and SDL_RENDERER_PRESENTVSYNC; info.name shows the driver actually used. This confirms whether your requests were granted or silently substituted.

Recovery options and limitations

Hardware acceleration can fail on headless, remote, or minimal-GPU environments. If SDL_CreateRenderer with accelerated flags returns NULL, retry with SDL_RENDERER_SOFTWARE as an explicit fallback and log SDL_GetError.

For diagnosis, force a driver via the SDL_HINT_RENDER_DRIVER hint before SDL_Init (for example, "software") to test the fallback path. Do not ship with a forced driver.

On macOS and iOS, creating the window or running the loop off the main thread is undefined behavior. Keep SDL_Init, SDL_CreateWindow, and the event loop on the main thread.

High-DPI scaling and window size reporting differ across platforms; query drawable size with SDL_GL_GetDrawableSize or combine SDL_GetWindowSize with DPI queries if you need pixel-exact rendering.

Skipping SDL_Quit or destroying the window before the renderer leaks resources and can crash drivers on exit. The cleanup order above is the rollback for a state-changing run.