feat: type DDDisplayWrapper and CompatRenderer structs and vtables

Add two new typed display subsystem structs:

- DDDisplayWrapper (vtable 0x662EC8, 25 slots): CWormsApp rendering
interface subobject that manages the software framebuffer and
dispatches to renderer backends. All 25 slots mapped.

- CompatRenderer (vtable 0x676A90, 37 slots): DirectDraw/D3D rendering
backend wrapping IDirectDraw2/IDirectDrawSurface. Two-section vtable
for primary display (0-24) and offscreen surface ops (25-36).
Struct fields mapped including DDraw interfaces and surface pointers.

Update DDDisplay docs with corrected dispatch chain:
DDDisplay → DDDisplayWrapper → RendererBackend

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

crates/openwa-core/src/address.rs

@@ -71,7 +71,11 @@ pub mod va {
         STREAMING_AUDIO_RESET, STREAMING_AUDIO_STOP, STREAMING_AUDIO_TIMER_CALLBACK,
     };
     pub use crate::display::base::DISPLAY_BASE_VTABLE;
+    pub use crate::display::compat_renderer::{
+        CompatRendererVtable, COMPAT_RENDERER_VTABLE, DDRAW8_RENDERER_VTABLE,
+    };
     pub use crate::display::dd_display::DD_DISPLAY_VTABLE;
+    pub use crate::display::display_wrapper::{DDDisplayWrapperVtable, DD_DISPLAY_WRAPPER_VTABLE};
     pub use crate::display::palette::PALETTE_VTABLE;
     pub use crate::frontend::map_view::MAP_VIEW_VTABLE;
     pub use crate::input::controller::INPUT_CTRL_VTABLE;

crates/openwa-core/src/display/compat_renderer.rs

@@ -0,0 +1,199 @@
+use core::ffi::c_void;
+
+// CompatRenderer — DirectDraw/D3D rendering backend.
+// See CompatRenderer struct and CompatRendererVtable below for full docs.
+
+crate::define_addresses! {
+    class "DDraw8Renderer" {
+        vtable DDRAW8_RENDERER_VTABLE = 0x0067_67F8;
+    }
+}
+
+#[openwa_core::vtable(size = 37, va = 0x0067_6A90, class = "CompatRenderer")]
+pub struct CompatRendererVtable {
+    // =====================================================================
+    // Primary display management (slots 0-24)
+    // =====================================================================
+    /// init / DirectDrawCreate + QueryInterface(IDirectDraw2) (0x59D430)
+    #[slot(0)]
+    pub init: fn(this: *mut CompatRenderer, p2: u32, p3: u32),
+    /// set cooperative level — fullscreen exclusive or windowed (0x59D5F0)
+    #[slot(1)]
+    pub set_cooperative_level: fn(this: *mut CompatRenderer),
+    /// reset state — calls teardown, clears initialized flag (0x59D480)
+    #[slot(2)]
+    pub reset_state: fn(this: *mut CompatRenderer),
+    /// get display size — returns stored width/height from +0x3C/+0x40 (0x59D510)
+    #[slot(3)]
+    pub get_display_size: fn(this: *mut CompatRenderer, out_w: *mut u32, out_h: *mut u32),
+    /// enum display modes — IDirectDraw2::EnumDisplayModes (0x59D560)
+    #[slot(4)]
+    pub enum_display_modes: fn(this: *mut CompatRenderer, p2: u32, p3: u32),
+    // Slot 5: stub (CGameTask__vt19)
+    /// set display mode + create surfaces — the main initialization (0x59D6D0)
+    ///
+    /// Calls IDirectDraw2::SetDisplayMode, creates primary surface with back buffer
+    /// (fullscreen) or with clipper (windowed). ~0x3F2 bytes.
+    #[slot(6)]
+    pub set_display_mode: fn(this: *mut CompatRenderer, width: i32, height: i32),
+    /// teardown — release surfaces, restore display mode (0x59DAD0)
+    ///
+    /// Calls timeEndPeriod, releases primary/back/clipper surfaces,
+    /// calls IDirectDraw2::RestoreDisplayMode, LockWindowUpdate(NULL).
+    #[slot(7)]
+    pub teardown: fn(this: *mut CompatRenderer, p2: i32),
+    /// vsync stub — calls teardown with 0, effectively a no-op (0x59DCB0)
+    #[slot(8)]
+    pub vsync_stub: fn(this: *mut CompatRenderer),
+    /// set display dimensions — thin wrapper to slot 6 (0x59DCE0)
+    #[slot(9)]
+    pub set_display_dims: fn(this: *mut CompatRenderer, width: i32, height: i32),
+    /// restore display dimensions — calls slot 6 with stored w/h (0x59DCC0)
+    #[slot(10)]
+    pub restore_display_dims: fn(this: *mut CompatRenderer),
+    /// restore lost surface — IDirectDrawSurface::Restore on primary (0x59D4B0)
+    #[slot(11)]
+    pub restore_surface: fn(this: *mut CompatRenderer) -> u32,
+    // Slot 12: stub
+    /// flip / present — end-of-frame IDirectDrawSurface::Flip (0x59DB70)
+    ///
+    /// Handles DDERR_SURFACELOST by calling RestoreSurface and retrying.
+    #[slot(13)]
+    pub flip: fn(this: *mut CompatRenderer),
+    /// get hardware caps — IDirectDraw2::GetCaps for HAL and HEL (0x59DC80)
+    #[slot(14)]
+    pub get_caps: fn(this: *mut CompatRenderer, out: *mut u8),
+    /// lock primary surface (read, 16bpp flags) (0x59D370)
+    ///
+    /// Returns pitch and pixel pointer through output params.
+    #[slot(15)]
+    pub lock_primary_read:
+        fn(this: *mut CompatRenderer, out_pitch: *mut u32, out_ptr: *mut *mut u8),
+    /// unlock primary surface (0x59D3B0)
+    #[slot(16)]
+    pub unlock_primary_read: fn(this: *mut CompatRenderer),
+    /// lock primary surface (write, 32bpp flags) (0x59D390)
+    #[slot(17)]
+    pub lock_primary_write:
+        fn(this: *mut CompatRenderer, out_pitch: *mut u32, out_ptr: *mut *mut u8),
+    /// unlock primary surface — same fn as slot 16 (0x59D3B0)
+    #[slot(18)]
+    pub unlock_primary_write: fn(this: *mut CompatRenderer),
+    /// blt filled rect to screen — IDirectDrawSurface::Blt with DDBLT_COLORFILL (0x59DDD0)
+    #[slot(19)]
+    pub blt_fill_rect:
+        fn(this: *mut CompatRenderer, x: i32, y: i32, width: i32, height: i32, color: u32),
+    /// blt clear both surfaces — clears front and back buffer (0x59DD00)
+    #[slot(20)]
+    pub blt_clear_both: fn(this: *mut CompatRenderer),
+    /// blt clear current surface — clears active drawing surface (0x59DD70)
+    #[slot(21)]
+    pub blt_clear_current: fn(this: *mut CompatRenderer),
+    // Slots 22-23: stubs
+    /// striped blt helper — breaks area into horizontal bands (0x5A2080)
+    #[slot(24)]
+    pub blt_striped: fn(this: *mut CompatRenderer, surface: *mut u8, y_offset: i32),
+
+    // =====================================================================
+    // Offscreen surface sub-object (slots 25-36, via second vtable at +0x04)
+    // =====================================================================
+    /// sub-object destructor — releases offscreen surface (0x59E7B0)
+    #[slot(25)]
+    pub offscreen_destructor: fn(this: *mut CompatRenderer, flags: u8) -> *mut CompatRenderer,
+    /// lock offscreen surface (0x59DF10)
+    ///
+    /// Handles DDERR_SURFACELOST with restore+retry.
+    /// Returns pitch and pixel pointer (via ESI — usercall).
+    #[slot(26)]
+    pub lock_offscreen: fn(this: *mut CompatRenderer, out_pitch: *mut u32, out_ptr: *mut *mut u8),
+    /// unlock offscreen surface — IDirectDrawSurface::Unlock on +0x10 (0x59E020)
+    #[slot(27)]
+    pub unlock_offscreen: fn(this: *mut CompatRenderer),
+    /// lock offscreen surface variant (0x59E090)
+    #[slot(28)]
+    pub lock_offscreen_alt:
+        fn(this: *mut CompatRenderer, out_pitch: *mut u32, out_ptr: *mut *mut u8),
+    /// unlock offscreen surface — same fn as slot 27 (0x59E020)
+    #[slot(29)]
+    pub unlock_offscreen_alt: fn(this: *mut CompatRenderer),
+    /// create offscreen plain surface — IDirectDraw2::CreateSurface (0x59E1D0)
+    ///
+    /// Creates DDSCAPS_OFFSCREENPLAIN surface, width 4-byte aligned,
+    /// 8bpp or 32bpp. Falls back to system memory if VRAM alloc fails.
+    #[slot(30)]
+    pub create_offscreen_surface:
+        fn(this: *mut CompatRenderer, width: i32, height: i32, bpp: i32) -> u32,
+    /// release offscreen surface — IDirectDrawSurface::Release on +0x10 (0x59E3B0)
+    #[slot(31)]
+    pub release_offscreen_surface: fn(this: *mut CompatRenderer),
+    /// set color key on offscreen surface (0x59E3F0)
+    #[slot(32)]
+    pub set_color_key: fn(this: *mut CompatRenderer, color: u32),
+    /// get color key from offscreen surface (0x59E480)
+    #[slot(33)]
+    pub get_color_key: fn(this: *mut CompatRenderer, out_color: *mut u32),
+    /// is offscreen surface lost — restore if DDERR_SURFACELOST (0x59E780)
+    #[slot(34)]
+    pub is_lost: fn(this: *mut CompatRenderer) -> u32,
+    /// blt offscreen — IDirectDrawSurface::Blt with source/dest rects (0x59E4D0)
+    #[slot(35)]
+    pub blt_offscreen: fn(
+        this: *mut CompatRenderer,
+        dst_x: i32,
+        dst_y: i32,
+        dst_w: i32,
+        dst_h: i32,
+        src: *mut c_void,
+    ),
+    /// blt fast offscreen — IDirectDrawSurface::BltFast with mirror/colorkey (0x59E5F0)
+    #[slot(36)]
+    pub blt_fast_offscreen:
+        fn(this: *mut CompatRenderer, dst_x: i32, dst_y: i32, src: *mut c_void, flags: u32),
+}
+
+/// CompatRenderer struct — DirectDraw/D3D rendering backend.
+///
+/// Wraps IDirectDraw2 and IDirectDrawSurface interfaces for screen presentation.
+/// Selected for DIRECTDRAW8, DIRECTDRAW32, DIRECT3D_* display modes.
+#[repr(C)]
+pub struct CompatRenderer {
+    /// 0x00: Primary vtable pointer (0x676A90)
+    pub vtable: *const CompatRendererVtable,
+    /// 0x04: Sub-object vtable pointer (offscreen surface ops, slots 25-36)
+    pub offscreen_vtable: *const c_void,
+    /// 0x08: Unknown
+    pub _unknown_08: u32,
+    /// 0x0C: IDirectDraw2 interface (used for offscreen surface creation)
+    pub ddraw2_offscreen: *mut c_void,
+    /// 0x10: IDirectDrawSurface (current offscreen surface)
+    pub offscreen_surface: *mut c_void,
+    /// 0x14: Timer period flag
+    pub timer_period: u32,
+    /// 0x18: Initialized flag (1 = DirectDraw created)
+    pub initialized: u32,
+    /// 0x1C: Unknown
+    pub _unknown_1c: u32,
+    /// 0x20: Windowed mode flag (0 = fullscreen exclusive, nonzero = windowed)
+    pub windowed: u32,
+    /// 0x24: Display mode field
+    pub display_mode: u32,
+    /// 0x28: IDirectDraw2 main interface
+    pub ddraw2_main: *mut c_void,
+    /// 0x2C: IDirectDrawSurface — primary/front surface
+    pub primary_surface: *mut c_void,
+    /// 0x30: IDirectDrawSurface — back buffer (windowed mode)
+    pub back_buffer: *mut c_void,
+    /// 0x34: Unknown
+    pub _unknown_34: u32,
+    /// 0x38: IDirectDrawClipper (windowed mode only)
+    pub clipper: *mut c_void,
+    /// 0x3C: Stored width
+    pub width: u32,
+    /// 0x40: Stored height
+    pub height: u32,
+}
+
+const _: () = assert!(core::mem::size_of::<CompatRenderer>() == 0x44);
+
+// Generate calling wrappers: CompatRenderer::flip(), etc.
+bind_CompatRendererVtable!(CompatRenderer, vtable);

crates/openwa-core/src/display/dd_display.rs

@@ -7,15 +7,29 @@ use crate::fixed::Fixed;
 /// Destructor: 0x569CE0.
 ///
 /// Actual runtime type is DisplayGfx (0x24E28 bytes), which extends DisplayBase.
-/// Manages layers, sprites, fonts, palettes, and delegates to a renderer backend
-/// (CompatRenderer for D3D/DDraw, OpenGLCPU for OpenGL).
+/// Manages layers, sprites, fonts, palettes, and delegates rendering through
+/// DDDisplayWrapper (g_DDDisplayWrapper at 0x79D6D4), which in turn dispatches
+/// to a renderer backend (CompatRenderer for D3D/DDraw, OpenGLCPU for OpenGL).
 ///
-/// Key internal fields (offsets from DisplayBase):
-/// - 0x3548/0x354C: display width/height
-/// - 0x3550-0x355C: clip rect (x1, y1, x2, y2)
-/// - 0x3560/0x3564: camera offset (x, y)
+/// ## Dispatch chain
+///
+/// ```text
+/// DDDisplay  →  DDDisplayWrapper  →  RendererBackend
+///   vtable        (CWormsApp sub-      (CompatRenderer/
+///   0x66A218       object, vtable       OpenGLCPU/DDraw)
+///                  0x662EC8)
+/// ```
+///
+/// DDDisplay methods apply camera offset and clipping, then call through
+/// `g_DDDisplayWrapper->vtable[N]` for the actual rendering operation.
+///
+/// Key internal fields (offsets from start of DisplayGfx/DisplayBase):
+/// - 0x3548/0x354C: display width/height (pixels)
+/// - 0x3550-0x355C: clip rect (x1, y1, x2, y2, pixels)
+/// - 0x3560/0x3564: camera offset (x, y, pixels)
 /// - 0x3580-0x3584: bitmap vector (ptr, end)
-/// - 0x3D9C: renderer backend pointer
+/// - 0x3D98: render lock flag (cleared by FlushRender)
+/// - 0x3D9C: display context pointer (read during FlushRender)
 ///
 /// OPAQUE: Full struct layout not yet mapped (see DisplayGfx for size).
 #[repr(C)]

crates/openwa-core/src/display/display_wrapper.rs

@@ -0,0 +1,143 @@
+// DDDisplayWrapper — CWormsApp rendering interface subobject.
+// See DDDisplayWrapper struct and DDDisplayWrapperVtable below for full docs.
+
+crate::define_addresses! {
+    class "CWormsApp" {
+        /// CWormsApp__FlipSurface — dispatches to renderer backend vtable[1]
+        fn/Thiscall CWORMSAPP_FLIP_SURFACE = 0x005A_2700;
+        /// ConstructFrameBuffer — allocates software framebuffer, inits renderer
+        fn/Thiscall CONSTRUCT_FRAME_BUFFER_THISCALL = 0x005A_2430;
+        /// CWormsApp__ReleaseFrameBuffer
+        fn/Thiscall CWORMSAPP_RELEASE_FRAME_BUFFER = 0x005A_24A0;
+        /// CWormsApp__FillRect — lock surface, memset rows, unlock
+        fn/Thiscall CWORMSAPP_FILL_RECT = 0x005A_25C0;
+        /// CWormsApp__BlitToFrameBuffer — optimized blit from surface to framebuffer
+        fn/Thiscall CWORMSAPP_BLIT_TO_FRAME_BUFFER = 0x005A_2A40;
+        /// CWormsApp__DrawLandscape — blit with clipping and transparency
+        fn/Thiscall CWORMSAPP_DRAW_LANDSCAPE = 0x005A_2790;
+        /// ClearFrameBuffer — memset(framebuffer, 0, w*h)
+        fn CWORMSAPP_CLEAR_FRAME_BUFFER = 0x005A_23F0;
+    }
+}
+
+/// DDDisplayWrapper vtable (0x662EC8, 25 slots).
+///
+/// Many slots are thin thunks that forward to the renderer backend
+/// via `*(this+0x18)->vtable[N]`. Others manage the software framebuffer
+/// or perform blitting directly.
+///
+/// ## Slot categories
+///
+/// - **Renderer thunks** (0, 2, 4, 5, 8, 10, 11): Forward to backend
+/// - **Framebuffer management** (3, 6, 7, 9, 15/17, 16/18, 20): Manage G_FRAME_BUFFER_*
+/// - **Blitting** (19, 23, 24): FillRect, DrawLandscape, BlitToFrameBuffer
+/// - **Surface management** (12, 13, 22): Renderer queries and surface allocation
+/// - **Stub** (14): Returns 0
+#[openwa_core::vtable(size = 25, va = 0x0066_2EC8, class = "DDDisplayWrapper")]
+pub struct DDDisplayWrapperVtable {
+    /// renderer thunk -> backend vtable[0] (init/create) (0x4E3420, RET 0x8)
+    #[slot(0)]
+    pub renderer_init: fn(this: *mut DDDisplayWrapper, p2: u32, p3: u32),
+    /// flip/present — dispatches to renderer backend vtable[1] (0x5A2700)
+    #[slot(1)]
+    pub flip_surface: fn(this: *mut DDDisplayWrapper),
+    /// renderer thunk -> backend vtable[2] (reset state) (0x4E3440)
+    #[slot(2)]
+    pub renderer_reset: fn(this: *mut DDDisplayWrapper),
+    /// get framebuffer dimensions — reads G_FRAME_BUFFER_WIDTH/HEIGHT (0x5A2660, RET 0x4)
+    #[slot(3)]
+    pub get_framebuffer_dims: fn(this: *mut DDDisplayWrapper, out: *mut u32) -> u32,
+    /// renderer thunk -> backend vtable[4] (enum display modes) (0x4E3460, RET 0x8)
+    #[slot(4)]
+    pub renderer_enum_modes: fn(this: *mut DDDisplayWrapper, p2: u32, p3: u32),
+    /// renderer thunk -> backend vtable[5] (tail jump) (0x4E3480)
+    #[slot(5)]
+    pub renderer_slot5: fn(this: *mut DDDisplayWrapper),
+    /// construct framebuffer — wa_malloc(w*h), init renderer (0x5A2430, RET 0x8)
+    #[slot(6)]
+    pub construct_frame_buffer: fn(this: *mut DDDisplayWrapper, width: i32, height: i32) -> i32,
+    /// release framebuffer — calls renderer teardown, frees buffer (0x5A24A0)
+    #[slot(7)]
+    pub release_frame_buffer: fn(this: *mut DDDisplayWrapper, p2: i32),
+    /// renderer thunk -> backend vtable[8] (0x5A24F0)
+    #[slot(8)]
+    pub renderer_slot8: fn(this: *mut DDDisplayWrapper),
+    /// lock framebuffer for pixel access (0x5A2530)
+    ///
+    /// Returns framebuffer pointer and stride for direct pixel manipulation.
+    #[slot(9)]
+    pub lock_framebuffer:
+        fn(this: *mut DDDisplayWrapper, p2: u32, p3: u32, p4: u32, p5: u32) -> u32,
+    /// renderer thunk -> backend vtable[10] (0x5A2510)
+    #[slot(10)]
+    pub renderer_restore_dims: fn(this: *mut DDDisplayWrapper),
+    /// renderer thunk -> backend vtable[11] (restore surface) (0x5A25A0)
+    #[slot(11)]
+    pub renderer_restore_surface: fn(this: *mut DDDisplayWrapper),
+    /// allocate error/result object (0x5A2720, RET 0x4)
+    #[slot(12)]
+    pub alloc_error_result: fn(this: *mut DDDisplayWrapper, p2: u32) -> u32,
+    /// get renderer surface pointer (0x5A26C0)
+    ///
+    /// Queries `renderer->vtable[12]` with G_FRAME_BUFFER_PTR.
+    #[slot(13)]
+    pub get_renderer_surface: fn(this: *mut DDDisplayWrapper),
+    /// stub — returns 0 (CGameTask__vt18, 0x545780)
+    #[slot(14)]
+    pub stub_ret_zero: fn(this: *mut DDDisplayWrapper) -> u32,
+    /// lock surface for reading — returns framebuffer ptr + width (0x5A2690, RET 0x8)
+    #[slot(15)]
+    pub lock_surface_read: fn(this: *mut DDDisplayWrapper, p2: u32, p3: u32),
+    /// unlock surface (0x5A2C10, RET 0x4)
+    ///
+    /// No-op for software framebuffer — just returns success code.
+    #[slot(16)]
+    pub unlock_surface_read: fn(this: *mut DDDisplayWrapper, p2: u32),
+    /// lock surface for writing (0x5A2690 — same fn as slot 15, RET 0x8)
+    #[slot(17)]
+    pub lock_surface_write: fn(this: *mut DDDisplayWrapper, p2: u32, p3: u32),
+    /// unlock surface after writing (0x5A2C10 — same fn as slot 16, RET 0x4)
+    #[slot(18)]
+    pub unlock_surface_write: fn(this: *mut DDDisplayWrapper, p2: u32),
+    /// fill rectangle — lock, memset rows, unlock (0x5A25C0)
+    ///
+    /// Params: x, y, width, height, fill_value.
+    #[slot(19)]
+    pub fill_rect:
+        fn(this: *mut DDDisplayWrapper, x: i32, y: i32, width: i32, height: i32, fill_value: u32),
+    /// clear framebuffer — memset(ptr, 0, w*h) (0x5A23F0)
+    #[slot(20)]
+    pub clear_frame_buffer: fn(this: *mut DDDisplayWrapper),
+    /// trampoline to slot 20 via vtable dispatch (0x5A2420)
+    #[slot(21)]
+    pub clear_frame_buffer_indirect: fn(this: *mut DDDisplayWrapper),
+    /// allocate surface object — wa_malloc(0x14) (0x5A2760)
+    #[slot(22)]
+    pub alloc_surface: fn(this: *mut DDDisplayWrapper) -> *mut u8,
+    /// draw landscape — blit with clipping and optional color-key transparency (0x5A2790)
+    #[slot(23)]
+    pub draw_landscape:
+        fn(this: *mut DDDisplayWrapper, surface: *mut u8, y_offset: i32, flags: u32),
+    /// blit surface to framebuffer — optimized copy with stride alignment (0x5A2A40)
+    #[slot(24)]
+    pub blit_to_frame_buffer: fn(this: *mut DDDisplayWrapper, surface: *mut u8, y_offset: i32),
+}
+
+/// DDDisplayWrapper struct — CWormsApp rendering dispatch subobject.
+///
+/// Stored as a global pointer at 0x79D6D4 (g_DDDisplayWrapper).
+/// The full object layout is part of CWormsApp; only key fields are mapped here.
+#[repr(C)]
+pub struct DDDisplayWrapper {
+    /// 0x00: Vtable pointer (0x662EC8)
+    pub vtable: *const DDDisplayWrapperVtable,
+    /// 0x04-0x17: Unknown (part of CWormsApp layout)
+    pub _unknown_04: [u8; 0x14],
+    /// 0x18: Pointer to renderer backend (CompatRenderer, OpenGLCPU, or DDraw object)
+    pub renderer_backend: *mut u8,
+}
+
+const _: () = assert!(core::mem::size_of::<DDDisplayWrapper>() == 0x1C);
+
+// Generate calling wrappers: DDDisplayWrapper::flip_surface(), etc.
+bind_DDDisplayWrapperVtable!(DDDisplayWrapper, vtable);

crates/openwa-core/src/display/mod.rs

@@ -1,12 +1,16 @@
 pub mod base;
+pub mod compat_renderer;
 pub mod dd_display;
+pub mod display_wrapper;
 pub mod gfx;
 pub mod gradient;
 pub mod opengl;
 pub mod palette;
 
 pub use base::{DisplayBase, DisplayBaseVtable, SpriteBufferCtrl, SpriteCacheWrapper};
+pub use compat_renderer::CompatRenderer;
 pub use dd_display::DDDisplay;
+pub use display_wrapper::DDDisplayWrapper;
 pub use gfx::DisplayGfx;
 pub use opengl::OpenGLState;
 pub use palette::{Palette, PaletteVtable};