feat: define FramePostProcessHook abstract class + ScreenshotHook vtable

Adds the typed Rust definitions for the per-frame post-processing hook
interface used by `DisplayGfx::DispatchFramePostProcessHooks` (0x56CDB0)
and the slot 0 destructor's hook-vec teardown step:

- `FramePostProcessHook` — 4-byte abstract polymorphic class (just a
vtable pointer). Concrete subclasses store their state in globals.
- `FramePostProcessHookVtable` (0x66A2B8, 3 slots): scalar deleting
destructor + `get_capture_request` (returns non-zero if the hook
wants to run this frame) + `capture` (does the per-frame work,
receives `layer_0` as a stack arg).
- `ScreenshotHook` (`type` alias) and `SCREENSHOT_HOOK_VTABLE`
(0x66A2C4) — the only concrete subclass shipped in WA, writes the
rendered surface as a numbered PNG.

Calling conventions verified directly from
`DispatchFramePostProcessHooks` disasm:
- vtable[1] is pure thiscall (no stack args, returns i32 in EAX),
dispatched at 0x56CE01-0x56CE08.
- vtable[2] is thiscall + 1 stack arg (`layer_0: *mut DisplayBitGrid`
loaded from `DisplayGfx + 0x3D9C`), dispatched at 0x56CE98-0x56CEA8.

Adds 0xF6 (`TEST byte ptr [mem], imm8`) to the startup-check valid
prologue list — `FramePostProcessHook__Destructor` (0x569BF0) starts
with `TEST [ESP+4], 1` instead of a frame setup, which the prologue
sanity check did not previously recognize.

Pre-work for porting DisplayGfx::Destructor (slot 0).

crates/openwa-core/src/address.rs

@@ -82,6 +82,11 @@ pub mod va {
     };
     pub use crate::render::display::base::DISPLAY_BASE_VTABLE;
     pub use crate::render::display::context::{RenderContextVtable, RENDER_CONTEXT_VTABLE};
+    pub use crate::render::display::frame_hook::{
+        FramePostProcessHookVtable, FRAME_POST_PROCESS_HOOK_DESTRUCTOR,
+        FRAME_POST_PROCESS_HOOK_VTABLE, SCREENSHOT_HOOK_CAPTURE_TO_PNG,
+        SCREENSHOT_HOOK_GET_CAPTURE_REQUEST, SCREENSHOT_HOOK_VTABLE,
+    };
     pub use crate::render::display::gfx::{
         DISPLAY_BASE_DESTRUCTOR_IMPL, DISPLAY_GFX_DESTRUCTOR, DISPLAY_GFX_DESTRUCTOR_IMPL,
         DISPLAY_GFX_DISPATCH_FRAME_POST_PROCESS_HOOKS, DISPLAY_GFX_FREE_LAYER_SPRITE_TABLE,

crates/openwa-core/src/render/display/frame_hook.rs

@@ -0,0 +1,104 @@
+//! `FramePostProcessHook` — abstract per-frame post-processing hook.
+//!
+//! 4-byte polymorphic class (just a vtable pointer). Concrete subclasses
+//! override slots 1 and 2 of [`FramePostProcessHookVtable`] to implement
+//! per-frame work that runs after `DisplayGfx` finishes drawing the frame.
+//! Subclasses store their state in globals or are themselves singletons —
+//! the textbook "4-byte hook interface" pattern (lesson #34 in the display
+//! porting notes).
+//!
+//! The only concrete subclass shipped in WA is `ScreenshotHook` (vtable
+//! 0x66A2C4) which writes the rendered `layer_0` `DisplayBitGrid` as a
+//! numbered PNG when `g_DDGame->screenshot_pending` is set.
+//!
+//! ## Lifetime
+//!
+//! Lives in a `std::vector<FramePostProcessHook*>` at `DisplayGfx + 0x24DF8`
+//! (see `gfx.rs::hook_vec_proxy/first/last/end`). Inserted during
+//! `DisplayGfx::Init`, dispatched once per frame from `RenderFrame_Maybe`
+//! → `DispatchFramePostProcessHooks` (0x56CDB0), and freed by
+//! `DisplayGfx::DestructorImpl` (slot 0) which iterates the vec and calls
+//! `vtable[0](1)` on every entry.
+
+use crate::bitgrid::DisplayBitGrid;
+
+// Note: `FRAME_POST_PROCESS_HOOK_VTABLE` is emitted by the
+// `#[vtable(va = ...)]` attribute macro on `FramePostProcessHookVtable`
+// below; it does not need a separate `define_addresses!` entry.
+crate::define_addresses! {
+    class "FramePostProcessHook" {
+        /// `FramePostProcessHook::Destructor` (0x569BF0) — trivial:
+        /// rebinds vtable to base + frees if `flags & 1`.
+        fn/Thiscall FRAME_POST_PROCESS_HOOK_DESTRUCTOR = 0x0056_9BF0;
+    }
+
+    class "ScreenshotHook" {
+        /// Concrete `ScreenshotHook` vtable (0x66A2C4) — destructor +
+        /// `GetCaptureRequest` + `CaptureToPng`. Has the same shape as
+        /// `FramePostProcessHookVtable` (no Rust struct of its own,
+        /// since `ScreenshotHook` adds no instance fields).
+        vtable SCREENSHOT_HOOK_VTABLE = 0x0066_A2C4;
+        /// `ScreenshotHook::GetCaptureRequest` (0x56D170) — vtable[1].
+        /// Returns 2 if `g_DDGame->screenshot_pending` is set, else 0.
+        fn/Thiscall SCREENSHOT_HOOK_GET_CAPTURE_REQUEST = 0x0056_D170;
+        /// `ScreenshotHook::CaptureToPng` (0x56D180) — vtable[2].
+        /// Formats `"%s%06d.png"` and writes the rendered layer_0 surface
+        /// to disk via `FUN_0056C6F0`.
+        fn/Thiscall SCREENSHOT_HOOK_CAPTURE_TO_PNG = 0x0056_D180;
+    }
+}
+
+/// `FramePostProcessHook` — abstract polymorphic class (just a vtable ptr).
+///
+/// All instance state lives in the concrete subclass — for `ScreenshotHook`
+/// the "state" is `g_DDGame->screenshot_pending` and the running PNG counter
+/// in globals, not fields on the object itself.
+#[repr(C)]
+pub struct FramePostProcessHook {
+    pub vtable: *const FramePostProcessHookVtable,
+}
+
+const _: () = assert!(core::mem::size_of::<FramePostProcessHook>() == 4);
+
+/// Vtable for `FramePostProcessHook` (3 slots, 0x66A2B8).
+///
+/// Verified call conventions from the dispatcher
+/// `DisplayGfx::DispatchFramePostProcessHooks` (0x56CDB0):
+///
+/// - `vtable[1]` (`get_capture_request`) at 0x56CE01-0x56CE08: pure
+///   thiscall, no stack args, returns `i32` in EAX.
+/// - `vtable[2]` (`capture`) at 0x56CE98-0x56CEA8: thiscall, one stack
+///   arg `layer_0: *mut DisplayBitGrid` (loaded from
+///   `DisplayGfx + 0x3D9C`).
+/// - `vtable[0]` (destructor) is called from `DisplayGfx::DestructorImpl`
+///   at 0x56A1BF-0x56A1C5 with `flags = 1`.
+///
+/// Slots 1 and 2 are `_purecall` (pure virtual) on the abstract base vtable;
+/// only the concrete `ScreenshotHook` vtable provides real implementations.
+#[openwa_core::vtable(size = 3, va = 0x0066_A2B8, class = "FramePostProcessHook")]
+pub struct FramePostProcessHookVtable {
+    /// scalar deleting destructor (0x569BF0 on the base vtable).
+    /// Calls return value is `*mut FramePostProcessHook` per the MSVC ABI.
+    #[slot(0)]
+    pub destructor: fn(this: *mut FramePostProcessHook, flags: u32) -> *mut FramePostProcessHook,
+    /// `get_capture_request` — returns non-zero if this hook wants to run
+    /// this frame. ScreenshotHook returns 2 when a screenshot is pending,
+    /// 0 otherwise. The dispatcher tracks the max return value across all
+    /// hooks and only invokes `capture` if any hook returned non-zero.
+    #[slot(1)]
+    pub get_capture_request: fn(this: *mut FramePostProcessHook) -> i32,
+    /// `capture` — runs the hook's per-frame work, given the rendered
+    /// `layer_0` `DisplayBitGrid` from `DisplayGfx + 0x3D9C`.
+    #[slot(2)]
+    pub capture: fn(this: *mut FramePostProcessHook, layer_0: *mut DisplayBitGrid),
+}
+
+bind_FramePostProcessHookVtable!(FramePostProcessHook, vtable);
+
+/// `ScreenshotHook` — the only concrete subclass shipped in WA.
+///
+/// Layout matches `FramePostProcessHook` exactly (no instance fields). The
+/// vtable at 0x66A2C4 differs only in slots 1 and 2: `GetCaptureRequest`
+/// reads `g_DDGame->screenshot_pending`, and `CaptureToPng` writes the
+/// rendered surface to a numbered `.png` file.
+pub type ScreenshotHook = FramePostProcessHook;

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

@@ -1,6 +1,7 @@
 pub mod base;
 pub mod context;
 pub mod font;
+pub mod frame_hook;
 pub mod gfx;
 pub mod gradient;
 pub mod layer;

crates/openwa-dll/src/startup_checks.rs

@@ -39,6 +39,7 @@ const VALID_PROLOGUES: &[u8] = &[
     0xE8, // call rel32
     0xE9, // jmp rel32 (MinHook trampoline — function is hooked)
     0xEB, // jmp rel8 (short jump)
+    0xF6, // test byte ptr [mem], imm8 (e.g. FramePostProcessHook__Destructor's flag check)
     0xFF, // call/jmp [mem]
 ];