ReactOS 图形系统分析（16）：字符串对象 --- STROBJ（string.c）
1. 概述
string.c 位于 win32ss/gdi/eng/string.c，在《ReactOS 图形系统分析_4.md》模块表中被标注为「字符串绘制（IntEngTextOut 相关）」。深入源码后发现：该文件实际实现的是 STROBJ（String Object，字符串对象）的 DDI 服务函数 ，即 Windows 文本输出 DDI 契约中面向显示驱动的一组内核导出服务。
一个需要澄清的关键事实：ReactOS 当前并不存在 IntEngTextOut，EngTextOut 也仍是一个 stub （见 stubs.c(file:///d:/reactos/win32ss/gdi/eng/stubs.c)）。实际文本渲染走的是 FreeType 软件路径（freetype.c(file:///d:/reactos/win32ss/gdi/ntgdi/freetype.c) 的 IntExtTextOutW），STROBJ 机制尚未被接入渲染管线，属于为 DDI 文本输出契约预留的服务层。
┌─────────────────────────────────────────────────────────────┐
│ ntgdi/ 文本输出（实际渲染路径，非 STROBJ） │
│ NtGdiExtTextOutW → GreExtTextOutW → IntExtTextOutW │
│ → FreeType 栅格化字形 → EngCreateBitmap(8BPP 字形表面) │
│ → IntEngMaskBlt（用文本画刷绘制字形掩码） │
├─────────────────────────────────────────────────────────────┤
│ gdi/eng/string.c（本分析对象：STROBJ DDI 服务） │
│ 为 Windows DrvTextOut 驱动模型预留的服务函数 │
│ ├── STROBJ_dwGetCodePage ✓ 已实现 │
│ ├── STROBJ_fxBreakExtra ✓ 已实现 │
│ ├── STROBJ_fxCharacterExtra ✓ 已实现 │
│ ├── STROBJ_bEnum ✗ UNIMPLEMENTED │
│ ├── STROBJ_vEnumStart ✗ UNIMPLEMENTED │
│ ├── STROBJ_bEnumPositionsOnly ✗ UNIMPLEMENTED │
│ └── STROBJ_bGetAdvanceWidths ✗ UNIMPLEMENTED │
├─────────────────────────────────────────────────────────────┤
│ 显示驱动侧（Windows 模型） │
│ DrvTextOut(pso, pstro, pfo, ...) 通过 STROBJ_bEnum 枚举 │
│ 字形位置 (GLYPHPOS) 并逐字形绘制 │
└─────────────────────────────────────────────────────────────┘2. 核心数据结构
2.1 STROBJ --- DDI 公开字符串对象（winddi.h(file:///d:/reactos/sdk/include/psdk/winddi.h#L1164-L1171)）
c
typedef struct _STROBJ {
ULONG cGlyphs; // 字符串中的字形数量
FLONG flAccel; // 加速标志（SO_*，见 2.3）
ULONG ulCharInc; // 相邻字符的增量（单位字符），SO_CHAR_INC_EQUAL_BM_BASE 时有效
RECTL rclBkGround; // 背景矩形（用于背景填充/擦除）
GLYPHPOS *pgp; // 字形位置数组（首字形）
LPWSTR pwszOrg; // 原始字符串指针（宽字符）
} STROBJ;2.2 STRGDI --- 引擎内部扩展（text.h(file:///d:/reactos/win32ss/gdi/ntgdi/text.h#L23-L54)）
STROBJ 是公开头，引擎内部实际持有的是扩展的 STRGDI （= STROBJ + 文本输出状态机）。这正是 string.c 中 (PSTRGDI) pstro 强转的含义：
c
typedef struct _STRGDI
{
STROBJ StrObj; // 公开的 STROBJ 头
FLONG flTO; // 文本对象标志（TO_MEM_ALLOCATED 等）
INT cgposCopied; // 已复制到驱动的字形位置数
INT cgposPositionsEnumerated; // 已枚举位置数（枚举游标）
PVOID prfo; // PRFONT → PFONTGDI
PGLYPHPOS pgpos; // 当前字形位置指针
POINTFIX ptfxRef; // 参考点（基准原点，FIX 定点数）
POINTFIX ptfxUpdate; // 枚举增量
POINTFIX ptfxEscapement; // 字形推进向量（escapement）
RECTFX rcfx; // 字体矩形（FIX 定点）
FIX fxExtent; // 字符串范围（最大宽度）
FIX fxExtra; // 字符间距（character extra）
FIX fxBreakExtra; // 断词间距（break extra）
DWORD dwCodePage; // 代码页
INT cExtraRects; // 额外矩形数（ETO_CLIPPED 剪裁矩形）
RECTL arclExtra[3]; // 额外矩形数组
RECTL rclBackGroundSave; // 背景保存矩形
PWCHAR pwcPartition; // 分区指针（复杂文本/断词）
PLONG plPartition;
PLONG plNext;
PGLYPHPOS pgpNext;
PLONG plCurrentFont; // 当前字体游标（字体回退链）
POINTL ptlBaseLineAdjust; // 基线调整
INT cTTSysGlyphs; // 系统字形统计（TT/系统/默认字形）
INT cSysGlyphs;
INT cDefGlyphs;
INT cNumFaceNameGlyphs;
PVOID pacFaceNameGlyphs;
ULONG acFaceNameGlyphs[8]; // 面名字形
} STRGDI, *PSTRGDI;2.3 GLYPHPOS --- 字形位置（winddi.h(file:///d:/reactos/sdk/include/psdk/winddi.h#L970-L974)）
c
typedef struct _GLYPHPOS {
HGLYPH hg; // 字形句柄
GLYPHDEF *pgdf; // 字形数据（SO_ZERO_BEARINGS 时用；否则用 FONTOBJ_cGetGlyphs 取）
POINTL ptl; // 字形原点的设备坐标
} GLYPHPOS, *PGLYPHPOS;2.4 flAccel 加速标志（winddi.h(file:///d:/reactos/sdk/include/psdk/winddi.h#L1149-L1162)）
| 标志 | 含义 | 与 string.c 的关系 |
|---|---|---|
SO_FLAG_DEFAULT_PLACEMENT |
字形按默认放置（起点即第一个字形原点） | 枚举时驱动可直接用 pgp |
SO_HORIZONTAL / SO_VERTICAL |
水平/垂直排印 | 推进方向 |
SO_REVERSED |
反向排印（从右到左） | 枚举顺序 |
SO_ZERO_BEARINGS |
字形边界均为 0（仅 1-bit 掩码） | 需用 pgdf 而非 FONTOBJ_cGetGlyphs |
SO_CHAR_INC_EQUAL_BM_BASE |
字符增量 = 字形位图宽度 | 用 ulCharInc 快推进 |
SO_MAXEXT_EQUAL_BM_SIDE |
最大范围 = 字形位图边长 | 范围计算快路径 |
SO_GLYPHINDEX_TEXTOUT |
传入的是字形索引而非字符码 | 代码页/字符回退处理不同 |
SO_ESC_NOT_ORIENT |
escapement 与方向向量不等 | 推进向量处理 |
SO_DXDY |
使用 Dx/Dy 数组 | 逐字符推进 |
SO_CHARACTER_EXTRA |
有字符间距 | STROBJ_fxCharacterExtra 读取 fxExtra |
SO_BREAK_EXTRA |
有断词间距 | STROBJ_fxBreakExtra 读取 fxBreakExtra |
3. 函数实现明细
3.1 已实现（3 个）
c
/* 返回字符串所属代码页：直接读取扩展结构字段 */
DWORD STROBJ_dwGetCodePage(IN STROBJ *pstro)
{
PSTRGDI pStrGdi = (PSTRGDI) pstro;
return pStrGdi->dwCodePage;
}
/* 断词间距：仅当 flAccel 声明 SO_BREAK_EXTRA 时才有效 */
FIX STROBJ_fxBreakExtra(IN STROBJ *StringObj)
{
PSTRGDI pStrGdi = (PSTRGDI) StringObj;
if (pStrGdi->StrObj.flAccel & SO_BREAK_EXTRA) return pStrGdi->fxBreakExtra;
return (FIX) 0;
}
/* 字符间距：仅当 flAccel 声明 SO_CHARACTER_EXTRA 时才有效 */
FIX STROBJ_fxCharacterExtra(IN STROBJ *StringObj)
{
PSTRGDI pStrGdi = (PSTRGDI) StringObj;
if (pStrGdi->StrObj.flAccel & SO_CHARACTER_EXTRA) return pStrGdi->fxExtra;
return (FIX)0;
}模式说明： 三个已实现函数都是「只读服务」------驱动通过它们查询 STROBJ 携带的布局参数。注意 fxBreakExtra/fxCharacterExtra 的标志守卫：加速标志未置位时返回 0（Windows 语义中此时间距参数本身无意义）。
3.2 未实现（4 个桩）
| 函数 | Windows 语义 | 当前行为 |
|---|---|---|
STROBJ_bEnum |
枚举下一批字形位置（*pc 个 GLYPHPOS），返回 FALSE 表示枚举结束 |
UNIMPLEMENTED; return FALSE |
STROBJ_vEnumStart |
重置枚举游标到字符串开头 | UNIMPLEMENTED |
STROBJ_bEnumPositionsOnly |
仅枚举位置不返回字形数据（驱动只需布局） | UNIMPLEMENTED; return DDI_ERROR |
STROBJ_bGetAdvanceWidths |
批量获取字符推进宽度到 POINTQF 数组 |
UNIMPLEMENTED; return FALSE |
STROBJ_bEnum 是驱动文本输出最核心 的服务：Windows 驱动在 DrvTextOut 中循环调用它取出 GLYPHPOS 数组，对每个字形执行 FONTOBJ_cGetGlyphs + 位块绘制。其内部应基于 STRGDI 的 pgpos/cgposPositionsEnumerated/cgposCopied 推进游标------这些字段在结构里已定义好，但逻辑尚未实现。
4. 服务导出与调用链
STROBJ 函数不是普通内部函数，而是 win32k.sys 的导出 DDI 服务（与 EngXxx/FONTOBJ_xxx 同级），供显示/打印驱动调用：
4.1 内核驱动（KMD）调用路径
显示驱动 DrvTextOut(pso, pstro, pfo, pco, ...)
↓ 直接调用 win32k.sys 导出
win32k.spec: STROBJ_bEnum / STROBJ_vEnumStart / STROBJ_fxBreakExtra ...
↓
eng/string.c 实现win32k.spec 导出（win32k.spec(file:///d:/reactos/win32ss/win32k.spec#L214-L220)）：
@ stdcall STROBJ_bEnum(ptr ptr ptr)
@ stdcall STROBJ_bEnumPositionsOnly(ptr ptr ptr)
@ stdcall STROBJ_bGetAdvanceWidths(ptr long long ptr)
@ stdcall STROBJ_dwGetCodePage(ptr)
@ stdcall STROBJ_fxBreakExtra(ptr)
@ stdcall STROBJ_fxCharacterExtra(ptr)
@ stdcall STROBJ_vEnumStart(ptr)4.2 用户模式驱动（UMPD）调用路径
UMPD（用户模式打印/显示驱动，如 unidrv）
↓ 调 gdi32.dll 导出
gdi32.spec: STROBJ_bEnum → NtGdiSTROBJ_bEnum ...
↓ 经 win32u 系统调用进入内核
umpdstubs.c: NtGdiSTROBJ_bEnum / bEnumPositionsOnly / bGetAdvanceWidths / vEnumStart / dwGetCodePage
↓
eng/string.c 实现umpdstubs.c(file:///d:/reactos/win32ss/gdi/eng/umpdstubs.c#L620-L675) 中 5 个 NtGdiSTROBJ_* 系统调用处理函数当前也都是 UNIMPLEMENTED，直接转发到 string.c 的对应实现（此处与 string.c 桩函数同名同行为，实际未接线）。
内核 UMPD 调用链：
gdi32.dll STROBJ_* → NtGdiSTROBJ_*（win32u 转发） → umpdstubs.c → eng/string.c5. 对照：ReactOS 实际文本渲染管线
string.c 是「按 DDI 契约预留」，但 ReactOS 当前渲染根本不经过它。真实路径在 freetype.c(file:///d:/reactos/win32ss/gdi/ntgdi/freetype.c#L6727-L6789)：
#mermaid-svg-EaRt0eRZjSqEzNmr{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-EaRt0eRZjSqEzNmr .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-EaRt0eRZjSqEzNmr .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-EaRt0eRZjSqEzNmr .error-icon{fill:#552222;}#mermaid-svg-EaRt0eRZjSqEzNmr .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-EaRt0eRZjSqEzNmr .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-EaRt0eRZjSqEzNmr .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-EaRt0eRZjSqEzNmr .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-EaRt0eRZjSqEzNmr .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-EaRt0eRZjSqEzNmr .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-EaRt0eRZjSqEzNmr .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-EaRt0eRZjSqEzNmr .marker{fill:#333333;stroke:#333333;}#mermaid-svg-EaRt0eRZjSqEzNmr .marker.cross{stroke:#333333;}#mermaid-svg-EaRt0eRZjSqEzNmr svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-EaRt0eRZjSqEzNmr p{margin:0;}#mermaid-svg-EaRt0eRZjSqEzNmr .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-EaRt0eRZjSqEzNmr .cluster-label text{fill:#333;}#mermaid-svg-EaRt0eRZjSqEzNmr .cluster-label span{color:#333;}#mermaid-svg-EaRt0eRZjSqEzNmr .cluster-label span p{background-color:transparent;}#mermaid-svg-EaRt0eRZjSqEzNmr .label text,#mermaid-svg-EaRt0eRZjSqEzNmr span{fill:#333;color:#333;}#mermaid-svg-EaRt0eRZjSqEzNmr .node rect,#mermaid-svg-EaRt0eRZjSqEzNmr .node circle,#mermaid-svg-EaRt0eRZjSqEzNmr .node ellipse,#mermaid-svg-EaRt0eRZjSqEzNmr .node polygon,#mermaid-svg-EaRt0eRZjSqEzNmr .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-EaRt0eRZjSqEzNmr .rough-node .label text,#mermaid-svg-EaRt0eRZjSqEzNmr .node .label text,#mermaid-svg-EaRt0eRZjSqEzNmr .image-shape .label,#mermaid-svg-EaRt0eRZjSqEzNmr .icon-shape .label{text-anchor:middle;}#mermaid-svg-EaRt0eRZjSqEzNmr .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-EaRt0eRZjSqEzNmr .rough-node .label,#mermaid-svg-EaRt0eRZjSqEzNmr .node .label,#mermaid-svg-EaRt0eRZjSqEzNmr .image-shape .label,#mermaid-svg-EaRt0eRZjSqEzNmr .icon-shape .label{text-align:center;}#mermaid-svg-EaRt0eRZjSqEzNmr .node.clickable{cursor:pointer;}#mermaid-svg-EaRt0eRZjSqEzNmr .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-EaRt0eRZjSqEzNmr .arrowheadPath{fill:#333333;}#mermaid-svg-EaRt0eRZjSqEzNmr .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-EaRt0eRZjSqEzNmr .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-EaRt0eRZjSqEzNmr .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-EaRt0eRZjSqEzNmr .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-EaRt0eRZjSqEzNmr .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-EaRt0eRZjSqEzNmr .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-EaRt0eRZjSqEzNmr .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-EaRt0eRZjSqEzNmr .cluster text{fill:#333;}#mermaid-svg-EaRt0eRZjSqEzNmr .cluster span{color:#333;}#mermaid-svg-EaRt0eRZjSqEzNmr div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-EaRt0eRZjSqEzNmr .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-EaRt0eRZjSqEzNmr rect.text{fill:none;stroke-width:0;}#mermaid-svg-EaRt0eRZjSqEzNmr .icon-shape,#mermaid-svg-EaRt0eRZjSqEzNmr .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-EaRt0eRZjSqEzNmr .icon-shape p,#mermaid-svg-EaRt0eRZjSqEzNmr .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-EaRt0eRZjSqEzNmr .icon-shape .label rect,#mermaid-svg-EaRt0eRZjSqEzNmr .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-EaRt0eRZjSqEzNmr .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-EaRt0eRZjSqEzNmr .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-EaRt0eRZjSqEzNmr :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 是
否
是
否
是
否
应用程序: ExtTextOutW/TextOutW
gdi32.dll
NtGdiExtTextOutW
GreExtTextOutW
IntExtTextOutW (freetype.c)
路径处于打开状态?
PATH_ExtTextOut（记入路径）
内存 DC 无表面?
直接成功返回
LPtoDP 坐标变换
FONT_CACHE 查缓存
逐字符 FT_Get_Char_Index
FT_Load_Glyph 栅格化
EngCreateBitmap(8BPP 字形位图, BMF_TOPDOWN)
EngLockSurface
IntEngMaskBlt(psoDest, psoGlyph, ...,
文本画刷, 剪裁)
字形像素以画刷颜色
按掩码写入目标表面
有下划线/删除线?
IntEngFillBox / IntEngFillPolygon
更新 TA_UPDATECP 光标
要点：
- 字形栅格化 由 FreeType 完成（
FT_Load_Glyph→FT_BitmapGlyph），ReactOS 不依赖字体驱动提供的位图。 - 字形上屏 用
EngCreateBitmap把字形位图包成 8BPP 表面，再经IntEngMaskBlt（bitblt.c(file:///d:/reactos/win32ss/gdi/eng/bitblt.c#L1104-L1113)）以文本画刷颜色绘制------即"字形即掩码"。 - 完全没有 DrvTextOut / STROBJ 参与：framebuf 等显示驱动不实现 DrvTextOut（搜索 framebuf 源码无任何 TextOut 符号），因此不需要 STROBJ 服务。
- 这意味着 STROBJ 枚举、
EngTextOut、FONTOBJ_cGetGlyphs等 DDI 服务目前是死代码/预留代码------只有当未来实现 DrvTextOut 驱动模型（硬件文本加速或打印机驱动）时才会被激活。
6. 与《分析_4》标注的差异说明
《ReactOS 图形系统分析_4.md》模块表中对 string.c 的标注为「字符串绘制（IntEngTextOut 相关）」，与源码实际情况存在出入：
| 标注 | 实际情况 |
|---|---|
| 文件功能 | string.c 是 STROBJ（字符串对象）DDI 服务，不是文本绘制实现 |
| IntEngTextOut | 全代码库不存在该符号；EngTextOut 在 stubs.c 中是 stub |
| 文本输出 | 由 ntgdi/freetype.c 的 IntExtTextOutW 直接实现（FreeType + IntEngMaskBlt） |
建议将 _4.md 第 36 行的标注改为 ：字符串对象 STROBJ DDI 服务（DrvTextOut 契约预留；文本渲染见 ntgdi/freetype.c）。
7. 源码索引
| 文件 | 关键内容 |
|---|---|
| string.c(file:///d:/reactos/win32ss/gdi/eng/string.c) | STROBJ 服务：dwGetCodePage/fxBreakExtra/fxCharacterExtra 已实现；bEnum/vEnumStart/bEnumPositionsOnly/bGetAdvanceWidths 桩 |
| text.h(file:///d:/reactos/win32ss/gdi/ntgdi/text.h) | STRGDI 扩展结构、TO_* 标志 |
| winddi.h(file:///d:/reactos/sdk/include/psdk/winddi.h) | STROBJ/GLYPHPOS 结构、SO_* 加速标志 |
| stubs.c(file:///d:/reactos/win32ss/gdi/eng/stubs.c) | EngTextOut stub（真正的文本输出入口未实现） |
| umpdstubs.c(file:///d:/reactos/win32ss/gdi/eng/umpdstubs.c#L620-L675) | NtGdiSTROBJ_* 系统调用处理（UMPD 路径，桩） |
| freetype.c(file:///d:/reactos/win32ss/gdi/ntgdi/freetype.c#L6727-L7326) | IntExtTextOutW 实际文本渲染（FreeType 栅格化 + IntEngMaskBlt） |
| bitblt.c(file:///d:/reactos/win32ss/gdi/eng/bitblt.c#L1104) | IntEngMaskBlt（字形掩码上屏） |
关联模块：
- 上层调用者：ntgdi/(file:///d:/reactos/win32ss/gdi/ntgdi/)（NtGdiExtTextOutW 系统调用）
- DDI 消费方：显示驱动 DrvTextOut（ReactOS framebuf 未实现）、UMPD 打印驱动
- 相关 DDI 服务：
FONTOBJ_cGetGlyphs/FONTOBJ_vGetInfo（stubs.c 中同为桩）
本文档基于 ReactOS 源代码
win32ss/gdi/eng/string.c及关联模块分析（2026 年 8 月）