ReactOS 图形系统分析（25）：多显示器/平移显示与杂项 — multidisp.c / pandisp.c / engmisc.c

ReactOS 图形系统分析（25）：多显示器/平移显示与杂项 — multidisp.c / pandisp.c / engmisc.c

1. 概述

《分析_4》第 45~46 行把multidisp.c/pandisp.c（多显示器/平移显示）与engmisc.c（杂项）并列。三者实为三种角色：

平移显示（pandisp.c）是核心：它包装一个真实显示驱动（underlying PDEV），对外提供更大的虚拟桌面，内部把绘制重定向到"影子表面（shadow）"，再按需把**视口（viewport）**区域同步到物理屏幕。用户移动鼠标到屏幕边缘时视口随之滚动——这就是DEVMODE.dmPanningWidth/dmPanningHeight的语义。

DEVMODE: dmPelsWidth×dmPelsHeight（虚拟桌面） > dmPanningWidth×dmPanningHeight（物理屏幕） ┌─────────────────────────── 虚拟桌面 (szlDesktop) ───────────────────────────┐ │ │ │ ┌─────────────── 视口 rclViewport（物理屏幕大小） ───────────────┐ │ │ │ 光标移到边缘 → 视口滚动 (PanMovePointer) │ │ │ │ 绘制 → 影子表面 psoShadow → PanSynchronize 同步视口区域到屏幕 │ │ │ └───────────────────────────────────────────────────────────────┘ │ │ │ └────────────────────────────────────────────────────────────────────────────┘

2. 加载机制（pdevobj.c 的 vtable 替换）

[PDEVOBJ_pLoadPDEV/pEnableDisplay](file:///d:/reactos/win32ss/gdi/eng/pdevobj.c#L511-L575) 决定何时启用平移：

/* 1. META 设备 → 多显示器驱动（桩） */if(ldevtype==LDEV_DEVICE_META)pldev=LDEVOBJ_pLoadInternal(MultiEnableDriver,ldevtype);/* 2. 显示设备且请求了平移尺寸 → 用平移 vtable 覆盖驱动函数表 */if(ldevtype==LDEV_DEVICE_DISPLAY&&(dwAccelerationLevel>=5||pdm->dmFields&(DM_PANNINGWIDTH|DM_PANNINGHEIGHT))){/* 缺省填平：dmPanning* = dmPels* */if(!(pdm->dmFields&DM_PANNINGWIDTH))pdm->dmPanningWidth=pdm->dmPelsWidth;if(!(pdm->dmFields&DM_PANNINGHEIGHT))pdm->dmPanningHeight=pdm->dmPelsHeight;/* 用 gPanDispDrvFn 覆盖 ppdev->apfn 对应项 */for(i=0;i<gPanDispDrvCount;i++)ppdev->apfn[gPanDispDrvFn[i].iFunc]=gPanDispDrvFn[i].pfn;}elseppdev->pfn=ppdev->pldev->pfn;/* 普通驱动函数表 */

关键：平移驱动不是独立驱动模块，而是同一 PDEV 上对底层驱动函数表的包装层（vtable 替换），无需加载新 DLL。PANDEV保存了底层驱动的完整apfn[INDEX_LAST]表（用GETPFN(name)宏回调底层）。

3. PANDEV 结构与生命周期

3.1 PANDEV（[pandisp.c](file:///d:/reactos/win32ss/gdi/eng/pandisp.c#L19-L36)）

typedefstruct_PANDEV{ULONG iBitmapFormat;// 底层表面格式HDEV hdev;SIZEL szlDesktop;// 虚拟桌面大小（dmPelsW×H）RECTL rclViewport;// 视口（物理屏幕大小的漫游窗口）HSURF hsurf;// 设备表面（对引擎暴露，桌面大小）HSURF hsurfShadow;// 影子表面（实际绘制目标，内存位图）SURFOBJ*psoShadow;/* 底层 PDEV */ULONG flUnderlyingGraphicsCaps;SIZEL szlScreen;// 物理屏幕大小（dmPanningW×H）DHPDEV dhpdevScreen;// 底层 PDEV 句柄BOOL enabledScreen;// 底层表面是否已启用SURFOBJ*surfObjScreen;// 底层屏幕表面PFN apfn[INDEX_LAST];// 底层驱动函数表（包装回调用）}PANDEV,*PPANDEV;

3.2 生命周期 DDI

设计：对 GDI/引擎而言，设备表面是桌面大小；而真正可见的物理屏幕只是其中rclViewport一块。引擎的绘制都发生在影子表面（引擎可直接读写内存位图），再由同步机制拷到物理屏。

4. 绘制重定向与同步

4.1 重定向到影子表面

PanBitBlt(psoTrg,psoSrc,...){/* 设备表面 → 影子表面（源/目标都换） */if(psoTrg->iType==STYPE_DEVICE)psoTrg=pandev->psoShadow;if(psoSrc&&psoSrc->iType==STYPE_DEVICE)psoSrc=pandev->psoShadow;res=EngBitBlt(psoTrg,psoSrc,...);// 引擎软件绘制if(res)PanSynchronize(gPan,NULL);// 绘制完立刻同步（见下）returnres;}

同类包装：PanCopyBits（→PanBitBlt，ROP4_SRCCOPY）、PanAlphaBlend（→EngAlphaBlend到影子）、PanGradientFill（→EngGradientFill到影子）。PanStrokePath/PanTextOut未实现（UNIMPLEMENTED + ASSERT(FALSE)）。

4.2 同步 — PanSynchronize

PanSynchronize(dhpdev,prcl){/* FIXME: 当前整块拷贝影子缓冲，未按 prcl 局部优化 */ptlSrc=rclViewport.left/top;// 视口左上角rclDest=0,0,szlScreen.cx,szlScreen.cy;// 整块物理屏幕EngCopyBits(surfObjScreen,psoShadow,NULL,NULL,&rclDest,&ptlSrc);}

把影子表面中视口区域拷贝到物理屏幕表面（EngCopyBits）。注册为INDEX_DrvSynchronize，同时GCAPS2_SYNCFLUSH让引擎在绘制后调用；但源码 FIXME 明确：当前靠各绘制函数手动调用（GCAPS2_SYNCTIMER定时同步尚未实现，用全局gPan兜底）。

5. 视口漫游 — PanMovePointer

光标移到屏幕边缘时移动视口（GCAPS_PANNING语义）：

PanMovePointer(pso,x,y,prcl){/* 忽略隐藏/平移通知（无 DrvSetPointerShape，ASSERT x>=0 && y<0） */if(x<0||y>=0)return;if(底层支持 GCAPS_PANNING)底层MovePointer(...);// 透传底层光标y+=pso->sizlBitmap.cy;// 光标 y 相对屏幕底部换算/* 视口跟随光标：越左/右/上/下边缘则滚动 */if(x<rclViewport.left){rclViewport.left=x;right=x+szlScreen.cx;bChanged=TRUE;}elseif(x>=rclViewport.right){right=x+1;left=x-szlScreen.cx;bChanged=TRUE;}/* y 同理 */if(bChanged)PanSynchronize(dhpdev,NULL);// 滚动后立即同步}

6. 多显示器 — multidisp.c（桩）

MultiEnableDriver是LDEV_DEVICE_META（多显示器设备）的驱动入口——Windows 中由它聚合多个 PDEV 成统一桌面（与MDEVOBJ多显示器管理配套）。ReactOS 当前为UNIMPLEMENTED桩（恒返回 FALSE），即META 设备路径未启用，多显示器目前只靠mdevobj.c的 MDEV 映射对象做基础支持。

7. 杂项 — engmisc.c

7.1 IntEngEnter / IntEngLeave — 设备表面的"进入/离开"（核心工具）

问题：引擎软件绘制（BitBlt/AlphaBlend/StretchBlt/LineTo/TransBlt/Gradient）需要能直接读写像素（pvScan0/lDelta）的位图表面；而设备管理表面（无像素缓冲）无法直接操作。

IntEngEnter 解决：把设备表面换成"临时内存位图"再操作，结束后IntEngLeave用DrvCopyBits拷回：

IntEngEnter(&el,psoDest,&DestRect,ReadOnly,&Translate,&psoOutput){if(设备表面&&无 pvScan0){if(!HOOK_COPYBITS)returnFALSE;// 驱动不支持 CopyBits 则失败psoOutput=EngCreateBitmap(...);// 临时位图（目标区域大小）GDIDEVFUNCS(psoDest).CopyBits(psoOutput,psoDest,...);// 先把设备内容拷入Translate=-DestRect.left/top;// 坐标系平移到临时位图}elsepsoOutput=psoDest;// 位图表面直接用/* 若挂钩 HOOK_SYNCHRONIZE → 调用 SynchronizeSurface/Synchronize */}IntEngLeave(&el){if(OutputObj!=DestObj)// 用了临时位图{if(!ReadOnly)GDIDEVFUNCS(DestObj).CopyBits(DestObj,OutputObj,...);// 结果拷回设备表面释放临时位图+TrivialClipObj;}}

调用方（36 处）：[bitblt.c](file:///d:/reactos/win32ss/gdi/eng/bitblt.c#L965)、[alphablend.c](file:///d:/reactos/win32ss/gdi/eng/alphablend.c#L103)、[stretchblt.c](file:///d:/reactos/win32ss/gdi/eng/stretchblt.c#L205)、[lineto.c](file:///d:/reactos/win32ss/gdi/eng/lineto.c#L553)、[transblt.c](file:///d:/reactos/win32ss/gdi/eng/transblt.c#L40)、[gradient.c](file:///d:/reactos/win32ss/gdi/eng/gradient.c#L85)——这正是"引擎软件渲染能作用于设备表面"的通用桥梁（pandisp 的PanBitBlt回调EngBitBlt时即受益）。

7.2 其他杂项函数

8. 与《分析_4》标注对照

9. 源码索引

关联模块：

• 底层回调：EngBitBlt/EngAlphaBlend/EngGradientFill/EngCopyBits（《分析_4》3.1）
• 加载入口：LDEVOBJ_pLoadInternal（《分析_4》3.4）
• 设备对象：PDEVOBJ（ppdev->apfn 被替换）
• 光标联动：PanMovePointer与《分析_24》鼠标管理的交互（FIXME 提及 MouseSafety 误调）

10. 各函数作用和使用

10.1 pandisp.c — 平移显示驱动（DDI 函数表 gPanDispDrvFn）

共用说明：GETPFN(name)宏（pandev->apfn[INDEX_Drv##name]）用于回调底层驱动同名 DDI——所有 Pan* 函数都是"底层驱动函数的包装层"。

10.2 multidisp.c — 多显示器驱动入口

10.3 engmisc.c — 引擎杂项

本文档基于 ReactOS 源代码win32ss/gdi/eng/multidisp.c、pandisp.c、engmisc.c及关联模块分析（2026 年 8 月）