DxEmu - DirectDraw Emulation Layer

A DirectDraw API compatibility layer that enables legacy games from the 1990s-2000s to run on modern Windows systems by translating DirectDraw 7 calls to modern rendering backends (OpenGL or Direct3D 9).

Overview

DxEmu (ddraw.dll) is a drop-in replacement for the deprecated DirectDraw library that acts as an emulation layer. Instead of delegating to the original DirectDraw, it translates API calls to modern graphics APIs, allowing classic games to render on contemporary hardware.

Supported Games

Games tested and known to work (partially or fully):

• Arcanum
• Icewind Dale
• Diablo
• Wing Commander series
• State of War
• Theme Hospital
• Submarine Titans
• Command & Conquer series
• Worms series
• Fallout series
• Age of Empires
• Planescape Torment
• Throne of Darkness
• Civilization 2
• Jagged Alliance 2 Gold

See TODO.txt for comprehensive game list and known issues per title.

Architecture

Key Components

• DDraw Module (ddraw/): DirectDraw API implementation

  • Interface implementations (IDirectDraw 1-7, IDirectDrawSurface 1-7)
  • Surface management and blitting operations
  • Color space and pixel format conversions

• Rendering Backends:

  • OpenGL (default): GLRenderContext manages OpenGL 1.1-2.0 contexts
  • Direct3D 9: Placeholder implementation (not fully developed)
  • Software: CPU-based fallback rendering

• Core Infrastructure (dxemu/):

  • Base COM class with ref-counting
  • Centralized logging framework
  • Interface wrapper macros

• Input (dinput/): DirectInput stub for keyboard/mouse input

Rendering Mode

Build with exactly one rendering backend enabled via defines in ddraw/ddraw_common.hpp:

#define DDRAW_OPENGL   1   // Default: OpenGL rendering
#define DDRAW_DIRECT3D 0   // Alternative: Direct3D 9
#define DDRAW_SOFTWARE 0   // Fallback: CPU blitting

Building

Requirements

• Visual Studio 2010 or compatible C++ toolchain
• DirectX 7/8 SDK (included in 3rdparty/)
• CMFramework (external dependency, expected at ../CMFramework/)
• GLBind (external dependency, expected at ../GLBind/)
• Windows SDK for Win32 APIs

Build Steps

1. Open dxEmu.sln in Visual Studio
2. Select configuration:
   • Debug: Outputs to D:\Games\BS\
   • Release: Outputs to D:\Games\State of War\
3. Build solution (F7 or Build menu)

Output

• ddraw.dll (32-bit): Drop into game directory or system folder
• ddraw.lib: Import library for linking
• ddraw.pdb: Debug symbols

Note: Output paths are hardcoded in .vcxproj and target specific game directories. Modify OutDir property to change deployment location.

Installation

1. Copy ddraw.dll to your game's directory (same folder as the game executable)
2. Run the game normally
3. DxEmu will intercept DirectDraw calls and translate them to OpenGL

Debugging

Enable debug output in ddraw/ddraw_common.hpp:

#define DDRAW_DEBUG 1
#define DXEMU_DEBUG_TO_FILE 1

Debug artifacts written to ./DxEmu/ (relative to game executable):

• Logs/: API call logs and errors
• SurfaceSnapshots/: Surface bitmap dumps for visual debugging
• Shaders/: Compiled shader source code

Implementation Details

COM Interface Pattern

All DirectDraw interfaces follow a consistent wrapper pattern:

class CDirectDraw7 : DDrawIntefaceInheritance2(DirectDraw7)
{
    // Conditional compilation for proxy vs. native implementation
    #if DDRAW_PROXY
        LPDIRECTDRAW7 m_iddraw7;  // Pass-through to real ddraw
    #else
        GLRenderContext* m_renderContext;  // Native OpenGL rendering
    #endif
};

Surface Pipeline

1. CreateSurface: Allocates CDirectDrawSurface7 with memory layout
2. Lock: Maps surface memory to CPU or GPU buffers
3. Blit: Transfers/transforms pixels between surfaces
4. Flip: Swaps front/back buffers for animation
5. Unlock: Commits surface changes to rendering backend

Rendering Flow

• Windowed Mode: Renders to window's OpenGL context via WGL
• Fullscreen Mode: Creates full-screen window with exclusive rendering context
• Double Buffering: Managed via SwapBuffers() for smooth animation

Known Limitations

• Overlays: Not fully implemented
• Page Flipping: Edge cases may not work correctly
• Direct3D Backend: Incomplete; OpenGL is the only mature path
• Input: DirectInput stub only; mouse/keyboard minimal
• Fullscreen Transitions: Some games may not restore properly

See TODO.txt for game-specific workarounds and issues.

Development Guide

For contributing to DxEmu, see .github/copilot-instructions.md for architecture patterns, development workflows, and code conventions.

Adding a New Method

1. Declare in ddraw/iddraw*.hpp
2. Implement in ddraw/iddraw*.cpp
3. Add debug logging via DDrawDebugLog()
4. Wrap rendering-specific logic in #if DDRAW_OPENGL blocks

Debugging Rendering Issues

1. Enable debug snapshots: Set DXEMU_DEBUG_TO_FILE=1 in dxemu_common.hpp
2. Check surface dumps: Look in ./DxEmu/SurfaceSnapshots/
3. Search logs: Find API calls and errors in ./DxEmu/Logs/
4. Test with specific game from TODO.txt list

Performance

• OpenGL Backend: Hardware-accelerated; 60+ FPS on modern GPUs
• Software Backend: CPU-bound; typically 10-30 FPS (fallback only)
• Memory: Minimal overhead; surfaces allocated on first use

SSE2 instructions used for optimized pixel operations (EnableEnhancedInstructionSet=StreamingSIMDExtensions2).

License

MIT License - See LICENSE file for details.

Copyright © 2026 Gabriel Max (dev.zetta@gmail.com)

References

• DirectDraw 7 Documentation: MSDN
• Game Compatibility: See TODO.txt for per-game notes and workarounds
• Architecture: See .github/copilot-instructions.md for implementation patterns

Contributing

When modifying this codebase:

1. Follow the COM interface pattern established in existing code
2. Use the centralized logging framework (DDrawDebugLog)
3. Test with games from the TODO.txt compatibility list
4. Document game-specific workarounds in TODO.txt
5. Update this README if changing core architecture