DirectDraw API Reference

HRESULT WINAPI DirectDrawCreate(
    const GUID* lpGUID,
    LPDIRECTDRAW* lplpDD,
    IUnknown*     pUnkOuter
);

Creates a new DirectDraw device object backed by an SDL3 renderer. This is the entry point for all DirectDraw usage.

Parameters

Return values

Ownership and lifetime

Caller owns the returned object. Call Release() exactly once when done. All surfaces, palettes, and clippers created through this object hold their own references and are independent.

Behavioral difference from original DirectX 3

The original function consults the DirectDraw driver registry and can fail if no display driver is installed. free-direct always succeeds on any SDL3-capable platform.

ULONG WINAPI AddRef();

Increments the internal reference count by 1. Returns the new count.

Thread-safe: uses std::atomic<ULONG> internally.

ULONG WINAPI Release();

Decrements the reference count by 1 and returns the new count. When the count reaches 0, the object is destroyed:

• The SDL renderer is destroyed (SDL_DestroyRenderer).
• The window is restored from fullscreen via FreeApiSetWindowFullscreen(false).
• The SDL window handle is released (but not destroyed — the window belongs to the caller).

HRESULT WINAPI QueryInterface(const GUID& riid, void** ppvObject);

Always returns DDERR_UNSUPPORTED. COM interface promotion (e.g. to IDirectDraw2, IDirectDraw4) is not implemented.

HRESULT WINAPI SetCooperativeLevel(HWND hWnd, DWORD dwFlags);

Associates the DirectDraw object with a window, creates the SDL renderer for that window, and optionally requests fullscreen mode. Must be called before any surfaces are created.

Parameters

What happens internally

1. Stores hWnd and casts it to SDL_Window*.
2. If DDSCL_FULLSCREEN: calls FreeApiSetWindowFullscreen(true).
3. If DDSCL_NORMAL: calls FreeApiSetWindowFullscreen(false).
4. Destroys any pre-existing renderer attached to the window (legacy re-init pattern).
5. Calls SDL_CreateRenderer(sdlWindow, NULL) to create a hardware-accelerated renderer.
6. If the default renderer fails, falls back to SDL_CreateRenderer(sdlWindow, "software").
7. Enables VSync via SDL_SetRenderVSync(renderer, 1) unless FREE_DIRECT_ENABLE_VSYNC=0.

Return values

Limitations vs. original DirectX 3

• Does not acquire exclusive hardware access.
• DDSCL_EXCLUSIVE is accepted but provides no additional privilege.
• Multiple calls on the same object destroy and recreate the renderer.

HRESULT WINAPI SetDisplayMode(DWORD dwWidth, DWORD dwHeight, DWORD dwBPP);

Stores the game's logical rendering resolution and requests fullscreen mode. Does not change the physical display resolution.

Parameters

Side effect

Calls FreeApiSetWindowFullscreen(hwnd_, true) if a window has already been associated via SetCooperativeLevel. SDL3's logical presentation (letterbox scaling) is applied at first present.

Return values

HRESULT WINAPI CreateSurface(
    const DDSURFACEDESC*  lpDDSurfaceDesc,
    LPDIRECTDRAWSURFACE*  lplpDDSurface,
    IUnknown*             pUnkOuter
);

Creates a DirectDraw surface object. Allocates a CPU pixel buffer immediately. The exact type and dimensions depend on the descriptor.

Parameters

Supported surface types (determined by ddsCaps.dwCaps)

Return values

Pixel buffer layout after creation

• 8-bit: width × height bytes, one byte per pixel = palette index.
• 32-bit: width × height × 4 bytes, four bytes per pixel in R,G,B,A order.
• All pixels initialized to 0.

HRESULT WINAPI CreatePalette(
    DWORD                dwFlags,
    LPPALETTEENTRY       lpColorTable,
    LPDIRECTDRAWPALETTE* lplpDDPalette,
    IUnknown*            pUnkOuter
);

Creates a palette object holding up to 256 color entries.

Parameters

Return values

HRESULT WINAPI CreateClipper(
    DWORD                 dwFlags,
    LPDIRECTDRAWCLIPPER*  lplpDDClipper,
    IUnknown*             pUnkOuter
);

Creates a clipper object. In free-direct the clipper's main function is to signal that a surface is operating in windowed mode, enabling automatic screen-to-client coordinate translation during Blt calls on the primary surface.

Parameters

Return values

ULONG WINAPI AddRef();
ULONG WINAPI Release();

Standard reference counting. When Release() reaches 0:

• The SDL texture (if any) is destroyed via SDL_DestroyTexture.
• The attached palette (if any) has its reference released.
• The attached clipper (if any) has its reference released.
• Any attached DC is destroyed via FreeApiDestroySurfaceDC.
• The CPU pixel buffer (std::vector<uint8_t>) is freed.

HRESULT WINAPI QueryInterface(const GUID& riid, void** ppvObject);

Always returns DDERR_UNSUPPORTED. Interface promotion not implemented.

HRESULT WINAPI Blt(
    LPRECT               lpDestRect,
    LPDIRECTDRAWSURFACE  lpDDSrcSurface,
    LPRECT               lpSrcRect,
    DWORD                dwFlags,
    LPDDBLTFX            lpDDBltFx
);

General-purpose blit. Operates entirely in CPU memory. Two modes are supported: color fill (when DDBLT_COLORFILL is set) and surface-to-surface copy (when lpDDSrcSurface is non-NULL).

Parameters

Color fill mode (DDBLT_COLORFILL)

Fills the destination rectangle with a solid color from lpDDBltFx->dwFillColor:

• 32-bit surfaces: dwFillColor = 0x00RRGGBB. Alpha byte is set to 255 (opaque).
• 8-bit surfaces: the low byte of dwFillColor is used as the palette index. The color key value 0 makes index 0 transparent in subsequent blits.

Surface-to-surface copy

Copies pixels from the source surface rectangle to the destination rectangle:

• Nearest-neighbor scaling when source and destination rectangles have different sizes.
• Only 8→8 and 32→32 bit depth combinations are handled. Mixed depths (8→32 or 32→8) skip all pixels silently.
• Source color key is applied when DDBLT_KEYSRC is set and the source has a color key (see SetColorKey).

Auto-present behavior

If the destination is the primary surface, owner->renderer_ is non-NULL, and Flip() has never been called on the owning IDirectDraw instance, PresentPrimary is called automatically after a successful blit. This supports the Speedy Blupi pattern of blitting directly to the primary without a separate Flip call.

Return values

HRESULT WINAPI BltFast(
    DWORD                dwX,
    DWORD                dwY,
    LPDIRECTDRAWSURFACE  lpDDSrcSurface,
    LPRECT               lpSrcRect,
    DWORD                dwTrans
);

Fast surface-to-surface copy without scaling. Copies the source rectangle to position (dwX, dwY) on this surface. The destination rectangle is always the same size as the source rectangle.

Parameters

Return values

Auto-present behavior is the same as Blt.

HRESULT WINAPI Flip(
    LPDIRECTDRAWSURFACE  lpDDSurfaceTargetOverride,
    DWORD                dwFlags
);

Presents the primary surface to the screen by uploading the CPU pixel buffer to SDL and calling SDL_RenderPresent. This is not a real DirectDraw page flip. There is no flip chain; only the primary surface's CPU buffer is presented.

Parameters

Effect of calling Flip

After the first call to Flip():

• owner_->usesFlip_ is set to true.
• Auto-present from Blt / BltFast is disabled.
• Flip() becomes the only way to update the screen.

Presentation pipeline (called internally)

1. Frame throttle: if called within the frame interval (default 1000 ms / 60 = 16.67 ms) since the last present, returns DD_OK immediately.
2. Dirty check: if the primary surface pixel buffer has not been written since the last present, skips upload and present.
3. Palette expansion (8-bit only): expands all pixel indices to RGBA32 using the attached palette (or a default 3:3:2 palette if none is attached). Uses a cached paletteConvertBuffer_ to avoid per-frame heap allocation.
4. Texture upload: SDL_UpdateTexture uploads the pixel data to a cached streaming SDL_Texture (RGBA32, STREAMING access).
5. Render clear: SDL_RenderClear with black.
6. Logical presentation (once): SDL_SetRenderLogicalPresentation(renderer, W, H, SDL_LOGICAL_PRESENTATION_LETTERBOX) is called on the first present to set up letterbox scaling.
7. Render: SDL_RenderTexture(renderer, texture, NULL, NULL).
8. Present: SDL_RenderPresent exactly once.

Return values

HRESULT WINAPI Lock(
    LPRECT           lpDestRect,
    LPDDSURFACEDESC  lpDDSurfaceDesc,
    DWORD            dwFlags,
    HANDLE           hEvent
);

Provides direct CPU access to the surface's pixel buffer. Returns a pointer to the pixel data via lpDDSurfaceDesc->lpSurface. The lock is always immediately available — there is no GPU synchronization.

Parameters

Return values

HRESULT WINAPI Unlock(LPVOID lpSurfaceData);

No-op. Always returns DD_OK. The lpSurfaceData parameter is ignored. There is no hardware lock to release and the pixel buffer pointer remains valid.

HRESULT WINAPI GetSurfaceDesc(LPDDSURFACEDESC lpDDSurfaceDesc);

Fills a DDSURFACEDESC with the current surface properties. Caller must set dwSize = sizeof(DDSURFACEDESC) before calling. Returns the same information as Lock but without providing a pixel pointer for primary surfaces.

Parameters

Return values

HRESULT WINAPI SetColorKey(DWORD dwFlags, LPDDCOLORKEY lpDDColorKey);

Sets the color key for transparent blits from this surface. Only source blit color keys are supported.

Parameters

Color key comparison semantics

Return values

HRESULT WINAPI SetPalette(LPDIRECTDRAWPALETTE lpDDPalette);

Associates a palette with this surface. Reference-counted.

Parameters

Effect

• On an 8-bit primary surface: the palette is used during PresentPrimary to expand indices to RGBA32. If no palette is set, a default 3:3:2 palette is used.
• On an 8-bit offscreen surface: the palette is used during GetDC (expansion to RGBA32) and ReleaseDC (nearest-match quantization).
• On 32-bit surfaces: the palette is stored but has no effect on rendering.

Return values

HRESULT WINAPI SetClipper(LPDIRECTDRAWCLIPPER lpDDClipper);

Associates a clipper with this surface. Reference-counted.

Parameters

Effect

The presence of a clipper on the primary surface activates windowed-mode coordinate adjustment in Blt: destination rectangles expressed in screen coordinates are translated to window-local coordinates by subtracting the SDL window's position.

Return values

HRESULT WINAPI IsLost();

Always returns DD_OK (not lost). Surfaces in free-direct are CPU-resident and never lose their content. Legacy game code that polls IsLost() in a loop will not spin.

HRESULT WINAPI Restore();

Always returns DD_OK. No restoration is needed.

HRESULT WINAPI GetDC(HDC* lphDC);

Returns a GDI-compatible device context backed by the surface's pixel buffer. Needed by the DDColorMatch pattern: GetDC → SetPixel → Lock → read index back → Unlock → ReleaseDC.

Parameters

Behavior by surface format

Return values

HRESULT WINAPI ReleaseDC(HDC hDC);

Releases the device context returned by GetDC. For 8-bit surfaces, converts the modified temporary RGBA buffer back to palette indices using nearest-match squared-RGB distance for each pixel, then frees the temporary buffer. Destroys the DC so a fresh one is created on the next GetDC call.

Parameters

Return values

ULONG WINAPI AddRef();
ULONG WINAPI Release();

Standard reference counting. Release() to 0 frees the palette's 256-entry internal array.

HRESULT WINAPI GetEntries(
    DWORD           dwFlags,
    DWORD           dwBase,
    DWORD           dwNumEntries,
    LPPALETTEENTRY  lpEntries
);

Reads a contiguous range of palette entries into the caller-provided array.

Parameters

Return values

HRESULT WINAPI SetEntries(
    DWORD           dwFlags,
    DWORD           dwBase,
    DWORD           dwNumEntries,
    LPPALETTEENTRY  lpEntries
);

Writes a contiguous range of palette entries from the caller-provided array.

Parameters

Return values

ULONG WINAPI AddRef();
ULONG WINAPI Release();

Standard reference counting. Release() to 0 frees the clipper object.

HRESULT WINAPI SetHWnd(DWORD dwFlags, HWND hWnd);

Stores the HWND associated with this clipper.

Parameters

Return values

Limitation vs. original DirectX 3

In original DirectDraw, the clipper maintains a clip list (RGNDATA) based on the visible region of the HWND. free-direct does not maintain clip regions; it only uses the window position for coordinate translation.