Windows

本页只写 Windows 原生 surface 的平台差异。通用 attach、resize、异步 detach 和 release 规则见 Surface 接口；Session 的关闭顺序见生命周期概念。

可用性： 0.9 已发布 Win32 C ABI（migo.dll / migo.lib，x86_64 与 arm64）；migo_query_capabilities 会报告 MIGO_PLATFORM_WIN32_HWND。WinUI SwapChainPanel 仍是未来实现，不能按可用平台接入。

先查 `platform_kinds`

MigoCapabilities.platform_kinds 的第 N 位表示值为 N 的 MIGO_PLATFORM_* 是否可 attach。Win32 的值为 2：

#include <migo/capabilities.h>

MigoCapabilities caps;
caps.struct_size = (uint32_t)sizeof caps;
caps.abi_version = MIGO_ABI_VERSION_CURRENT;
if (migo_query_capabilities(&caps) != MIGO_OK ||
    (caps.platform_kinds & (1ULL << MIGO_PLATFORM_WIN32_HWND)) == 0)
    return; /* 当前 DLL 不支持 Win32 surface；不要继续 attach。 */

Win32：子 `HWND`

描述符

#include <migo/platform/win32.h>

typedef struct MigoWin32HwndDescriptor {
    uint32_t             struct_size;
    uint32_t             abi_version;
    MigoPlatformKind     platform_kind; /* MIGO_PLATFORM_WIN32_HWND */
    MigoPlatformDescriptorFlags flags; /* 须为 0 */
    void                *hwnd;          /* host-owned child HWND */
} MigoWin32HwndDescriptor;

hwnd 必须是宿主拥有的子窗口。引擎使用 Windows 的 ANGLE / Direct3D 路径，但不拥有 HWND，也不接管宿主 message loop。首个成功 attach 会固定 Session 的 ANGLE device；之后替换 HWND 时必须仍属于同一 ANGLE device，否则返回 MIGO_ERROR_INVALID_STATE。

Attach

MigoWin32HwndDescriptor plat;
memset(&plat, 0, sizeof plat);
plat.struct_size   = (uint32_t)sizeof plat;
plat.abi_version   = MIGO_ABI_VERSION_CURRENT;
plat.platform_kind = MIGO_PLATFORM_WIN32_HWND;
plat.hwnd           = host_child_hwnd;

MigoSurfaceDescriptor desc;
memset(&desc, 0, sizeof desc);
desc.struct_size              = (uint32_t)sizeof desc;
desc.abi_version              = MIGO_ABI_VERSION_CURRENT;
desc.generation               = next_generation;
desc.platform_kind            = MIGO_PLATFORM_WIN32_HWND;
desc.width_pixels             = width;
desc.height_pixels            = height;
desc.scale_factor             = scale;
desc.color_space              = MIGO_COLOR_SPACE_SRGB;
desc.alpha_mode               = MIGO_ALPHA_MODE_OPAQUE;
desc.preferred_presentation_mode = MIGO_PRESENTATION_MODE_DEFAULT;
desc.capability_flags         = MIGO_SURFACE_CAPABILITY_NONE;
desc.platform_descriptor_size = (uint32_t)sizeof plat;
desc.platform_descriptor      = &plat;

MigoSurfaceAttachment *attachment = NULL;
MigoResult result = migo_session_attach_surface(session, &desc, &attachment);

hwnd 的创建、消息派发、resize 和销毁都由宿主负责。migo_surface_begin_detach 返回 MIGO_OK 后，继续保留 HWND 和它的消息循环；只有 migo_surface_release_query 报告 MIGO_SURFACE_RELEASE_RELEASED，才可调用 migo_surface_release_destroy 并销毁子窗口。

MigoSurfaceRelease *release = NULL;
if (migo_surface_begin_detach(attachment, &release) == MIGO_OK) {
    attachment = NULL; /* handle 已被消费 */
    /* 在宿主消息循环中反复 query，非阻塞；确认 RELEASED 后再 DestroyWindow。 */
}

不要把 HWND 当作 MigoWinuiSwapChainPanelDescriptor 的 payload，也不要在 detach 返回后立刻 DestroyWindow；两者都会绕过对应的生命周期合同。

WinUI：仅记录未来形状

#include <migo/platform/winui.h>

typedef struct MigoWinuiSwapChainPanelDescriptor {
    uint32_t             struct_size;
    uint32_t             abi_version;
    MigoPlatformKind     platform_kind; /* MIGO_PLATFORM_WINUI_SWAP_CHAIN_PANEL */
    MigoPlatformDescriptorFlags flags;
    void                *swap_chain_panel_native; /* ISwapChainPanelNative* */
} MigoWinuiSwapChainPanelDescriptor;

swap_chain_panel_native 是 ISwapChainPanelNative 兼容的 COM 指针，不是 HWND。winui.h 明确将“引擎在 attach 前取得 COM 引用并在 RELEASED 前释放”标为未来实现；Windows README 也说明当前阶段不包含 WinUI 集成。因此 0.9 不应提交此 platform_kind，即使结构体已经出现在公共头文件中。

Windows

先查 platform_kinds

Win32：子 HWND

描述符

Attach

WinUI：仅记录未来形状

先查 `platform_kinds`

Win32：子 `HWND`