WindowsAppSDK中WinUI3应用使用LoadedImageSurface的解决方案

2025-06-17 09:01:05作者：宣聪麟

The Windows App SDK empowers all Windows desktop apps with modern Windows UI, APIs, and platform features, including back-compat support, shipped via NuGet.

项目地址：https://gitcode.com/gh_mirrors/wi/WindowsAppSDK

背景介绍

在WindowsAppSDK的WinUI3应用开发中，开发者有时需要将图像转换为CompositionSurface作为Win2D效果的输入源，并最终生成CompositionBrush用于窗口的系统背景。然而，直接使用Windows.UI.Xaml.Media.LoadedImageSurface类时，即使在UI线程上创建了DispatcherQueueController，仍然会遇到异常问题。

问题分析

LoadedImageSurface是Windows.UI.Xaml命名空间下的类，它提供了一种便捷的方式来加载图像并生成CompositionSurface。但在WinUI3应用中直接使用时，会遇到以下两个主要问题：

需要初始化System Xaml环境
需要Windows.UI.Xaml.Application实例

这些问题源于WinUI3和系统Xaml之间的架构差异。WinUI3使用Microsoft.UI.Xaml命名空间，而LoadedImageSurface属于Windows.UI.Xaml命名空间，两者需要不同的初始化过程。

解决方案

方法一：初始化System Xaml环境

要在WinUI3应用中使用LoadedImageSurface，首先需要初始化System Xaml环境：

// 创建DispatcherQueueController
static winrt::Windows::System::DispatcherQueueController createSystemDispatcherQueueController()
{
    DispatcherQueueOptions options
    {
        sizeof(DispatcherQueueOptions),
        DQTYPE_THREAD_CURRENT,
        DQTAT_COM_NONE  // 注意此处应为DQTAT_COM_NONE
    };

    ::ABI::Windows::System::IDispatcherQueueController* ptr{ nullptr };
    winrt::check_hresult(CreateDispatcherQueueController(options, &ptr));
    return { ptr, take_ownership_from_abi };
}

// 初始化Windows Xaml管理器
auto m_manager = winrt::Windows::UI::Xaml::Hosting::WindowsXamlManager::InitializeForCurrentThread();

方法二：使用Direct2D替代方案

如果不想依赖System Xaml初始化，可以采用更底层的Direct2D方案：

初始化Direct3D/Direct2D和Compositor
创建CompositionGraphicsDevice
创建CompositionDrawingSurface
绘制到Surface

// 创建图形设备
winrt::Windows::UI::Composition::CompositionGraphicsDevice create_graphics_device()
{
    if (!m_compositor)
    {
        m_compositor = winrt::Windows::UI::Composition::Compositor();
    }

    auto comp_interop = m_compositor.as<ABI::Windows::UI::Composition::ICompositorInterop>();
    winrt::Windows::UI::Composition::CompositionGraphicsDevice graphics_device{ nullptr };
    check_hresult(comp_interop->CreateGraphicsDevice(m_d2d1_device.get(), 
        reinterpret_cast<ABI::Windows::UI::Composition::ICompositionGraphicsDevice**>(winrt::put_abi(graphics_device))));
    return graphics_device;
}

// 开始绘制
std::pair<winrt::com_ptr<ID2D1DeviceContext>, POINT> begin_draw(const winrt::Windows::UI::Composition::CompositionDrawingSurface &drawing_surface)
{
    auto drawing_surface_interop = drawing_surface.as<ABI::Windows::UI::Composition::ICompositionDrawingSurfaceInterop>();
    winrt::com_ptr<ID2D1DeviceContext> ds;
    POINT up_off{};
    check_hresult(drawing_surface_interop->BeginDraw(nullptr, IID_PPV_ARGS(ds.put()), &up_off);
    return std::make_pair(ds, up_off);
}

// 结束绘制
void end_draw(const winrt::Windows::UI::Composition::CompositionDrawingSurface &drawing_surface)
{
    auto drawing_surface_interop = drawing_surface.as<ABI::Windows::UI::Composition::ICompositionDrawingSurfaceInterop>();
    check_hresult(drawing_surface_interop->EndDraw());
}

技术细节说明

DispatcherQueueOptions配置：当threadType为DQTYPE_THREAD_CURRENT时，应使用DQTAT_COM_NONE，这是官方文档明确指出的。
Direct2D方案特点：
- 使用ID2D1Device创建CompositionGraphicsDevice
- 通过ICompositionSurfaceInterop控制绘制
- 必须使用ID2D1DeviceContext而不是更高版本
- 绘制完成后必须调用EndDraw
Surface绘制机制：
- 传入ID3D11Device时，只能从BeginDraw获取IDXGISurface/ID3D11Texture2D
- 传入ID2D1Device时，会自动创建设备上下文和位图目标

最佳实践建议

对于简单的图像加载需求，推荐使用方法一的System Xaml初始化方案，代码更简洁。
对于性能要求高或复杂的图形处理场景，建议采用方法二的Direct2D方案，虽然代码量较大，但不依赖System Xaml，性能更好。
在WinUI3应用中，应尽量避免混合使用Windows.UI.Xaml和Microsoft.UI.Xaml命名空间的API，以减少潜在的兼容性问题。
如果必须使用Windows.UI.Composition命名空间的API，可以考虑将其封装为独立的模块，与主应用的UI逻辑分离。

通过以上方案，开发者可以在WinUI3应用中灵活地处理图像到CompositionSurface的转换需求，为创建丰富的视觉效果提供了可靠的技术基础。

WindowsAppSDK