DreamGUI
核心概念

文本

文本系统:距离场(MTSDF)默认字体、来自提示覆盖字形的小字号、回退字面与彩色 emoji、盒子优先的溢出处理与 Margin、LineHeightPercentage、WrapTextAt 和 Best Fit,富文本,渐变文字,按文化断行,增量布局,以及 DreamGUI.Text.* 控制台变量。

文本由 UDreamText 视觉绘制(Text,在 .dui 中)。它的度量对照 Chrome 和 Slate 校过,凡是不同的地方都重写了:字素簇和双向文本层级、连字、CSS 行盒、按 Unicode 范围选择的回退字面、文化和呈现方式、真正的粗体和斜体字面、彩色 emoji、两端对齐、制表位和中间省略。

盒子优先

UMG 的 TextBlock 不会溢出,因为它的盒子是从文本推出来的;你控制的是换行。这里矩形是写出来的,文本在盒子里对齐,放不下时由 OverflowType 决定怎么办:

OverflowType放不下时
HorizontalOverflow字符横向跑出矩形
VerticalOverflow(默认)换行,纵向跑出矩形
Truncate去掉右边放不下的字符
Ellipsis用 ... 替换放不下的部分
MiddleEllipsis每行放不下时把中间换成 ...,保留开头和结尾(Slate 的 MiddleEllipsis);换行时改为最后一行的末尾省略

bAutoWrapText 让其他策略也换行(UMG 的 AutoWrapText):配 Ellipsis 得到一段最后一行被省略的段落,配 Truncate 得到一段在盒子底部被截断的段落。对齐是 HAlign(Left、Center、Right、Justify)和 VAlign(Top、Middle、Bottom)。

盒子是写出来的,所以有了 UMG 用不着的控制:

属性作用
Margin矩形和文本之间的内边距,像 UMG 文本的 Margin。文本的换行、对齐和溢出测试都针对矩形减去它,所以它会收窄换行宽度,而不只是挪一下结果;它也会加进文本的首选尺寸
LineHeightPercentage缩放从一行到下一行的距离,1 为字体自身的行高。只有间距变化,字形大小不变。FontSpace.Y 是在此之上额外增加的固定距离:一个随字体缩放,另一个不随
WrapTextAt按此宽度而非内容盒的宽度换行;为零或更小则使用内容盒。盒子同时也是文本对齐的基准,因此更窄的换行宽度会得到一窄列文字,仍在整个控件上居中。它不会截断:Truncate 和 Ellipsis 仍按盒子测量
MinDesiredWidth向按内容定尺寸的父级报告的宽度下限,让一个暂时很短的标签(倒数的数字、还没到的名字)不把整行压塌
bBestFit / BestFitMinSizeBest Fit:缩小字号直到文本放进内容盒。FontSize 变成文本允许达到的字号,BestFitMinSize 是最小能缩到多少,再小就任它溢出。GetRenderedFontSize 是实际画出的字号

Best Fit 来自 uGUI,UMG 和 Slate 都没有:它们的文本按内容定尺寸,盒子随文本长大;这里盒子是写出来的,恰恰是需要它的情况。在面板里测量一段会换行的文本有一个坑,见布局最后一节。

Widget Panel {
    Text Body {
        AnchorData.SizeDelta = (360, 120)
        Text = "The box is authored: the text is aligned in it, and what does not fit is handled by OverflowType."
        FontSize = 16
        OverflowType = Ellipsis
        bAutoWrapText = true
        Margin = (12, 8, 12, 8)
        LineHeightPercentage = 1.2
    }

    Text Price {
        AnchorData.SizeDelta = (120, 40)
        Text = "1,234,567"
        FontSize = 32
        bBestFit = true
        BestFitMinSize = 12
    }

    Text Score {
        bRichText = true
        Text = "Score <size=40><gradient=Gold>9999</gradient></size>"
    }
}

其他排版属性:bUseKerning、bLigatures(默认开)、FontSpace(字距与行距的固定加量)、TabSize(制表位,以空格计,默认 8,CSS 的 tab-size)、TextJustify 和 LastLineAlign(两端对齐时额外空间加在哪、最后一行怎么对齐)、TextTransform(只改绘出的显示大小写;作者写的文本保留)、FlowDirection(Auto 交给双向算法),以及 bUnderline 和 bStrikethrough(富文本的 <u> 和 <s> 叠在它们之上)。

字体

字体是资产,一条继承链上是四个类型:抽象基类 UDreamUIFontData_BaseObject(「字体数据能做什么」的全部接口——字形、整形字面、行高、回退字面),中间抽象子类 UDreamUIFontData_FreeTypeRender(用 FreeType 读字体文件),以及它的两个子类——距离场字体 UDreamUIFontData_DistanceField(插件默认字体用这个)和位图字体 UDreamUIFontData_Bitmap。⚠️ 源码批注写明 _Bitmap 已不再维护,新功能不再为它实现。项目默认字体在 UDreamGUISettings::DefaultFont。

  • 默认字体就是 Slate 的:Roboto,带真正的常规、粗体、斜体、粗斜体字面,CJK 用 DroidSansFallback,画在轮廓多通道距离场上(/DreamGUI/DefaultFont_DistanceField)。
  • 距离场。 SdfSource 默认 OutlineMultiChannel(MTSDF:拐角更锐利,BGRA 图集)。描边、下衬(投影)、发光和歌词式填充(TextStyle,即 FDreamTextStyle)由内置着色器画,所以需要距离场字体并且开着 Use Built-in UI Shader;它们的长度以 em 计,所以同一个样式在任何字号下看起来一样。样式按控件存进画布的控件属性纹理,所以样式不同的文本仍然合进同一个 draw call。
  • 特效绘制在整个文本下方。 文本先绘制每个字形的底衬,再绘制每个字形的辉光和描边,最后绘制每个字形本体——就像阴影位于整段文字的下方,描边等一并如此。当字母重叠时(字距过紧或为负、斜体、粗重的窄体字形),后一个字母的阴影仍位于当前字母的描边和本体下方,其描边位于当前字母的本体下方。同时带底衬和描边或辉光的文本,每个字形绘制三个四边形而不是两个。
  • 粗体和斜体。 BoldFont、ItalicFont 和 BoldItalicFont 指向真正的字面;没有时才用合成的。
  • 回退字面。 Fallbacks 中的每一项(FDreamUIFontFallback)都有 Font、Ranges(码点)、Cultures(适用的语言)、一个 Scale 和 bPreferOverPrimary。旧的 FallbackFontArray 在加载时会转成使用默认设置的 Fallbacks 项。中文文化名会被补回书写体系(zh-Hans、zh-Hant),因此针对它们编写的回退在打包后的游戏中也能匹配。
  • 没有任何字型包含的字符。 当某个字符既不在字体自身的字型中,也不在其任何回退项中时,DreamGUI 会针对该字体记录一次警告,并指出码点(has no glyph for U+4E2D),文本会在对应位置显示一个方框或不显示任何内容。请为文本指定一个覆盖该字符的字体,或为该字体添加一个回退项。默认字体通过 /DreamGUI/DefaultFont_DistanceField_CJK 覆盖中文、日文和韩文;而你自己仅覆盖拉丁字符的字体则不会,这通常是该警告的常见原因。
  • 轮廓重叠。 一个字形若由相互交叠的独立笔画绘制而成——可变字体绘制其字形的方式,以及从可变字体切出的静态实例在未移除重叠时保留这些笔画的方式——在笔画交叉处的距离场中可能出现缺口或接缝;一条自身回绕的轮廓可能整块丢失。它的轮廓是正确的,FreeType 填充它也是正确的;无法跟随它的是场生成器。DreamGUI 会测量它光栅化的每个字形的重叠,并对每个字体警告一次,指出第一个这样的字形及其文件(引擎自带的字体,例如默认 CJK 回退字体,只在日志中说明)。从文件中移除重叠并改用该文件:先 pip install fonttools skia-pathops,再 python -c "from fontTools.ttLib import TTFont; from fontTools.ttLib.removeOverlaps import removeOverlaps; f = TTFont('in.ttf'); removeOverlaps(f); f.save('out.ttf')",或用 fonttools varLib.instancer --remove-overlaps 切出实例。
  • 彩色 emoji:CBDT/CBLC、sbix 和 COLRv0;bPreferColorEmoji 默认开。阴影、描边和长阴影修改器给彩色 emoji 做的拷贝是剪影。

怎么随游戏发出字体文件、彩色 emoji 字体和 ICU 数据,见字体与打包。

小字号

小字号的屏幕文本——每 em 不超过 SmallTextMaxPixelSize 个设备像素,默认 20——从放在设备像素网格上的提示覆盖字形绘制,和 Slate 一样清晰(UDreamGUISettings::bSmallTextCoverage,默认开)。更大的字照常从距离场画。

  • 带描边、发光或下衬的小字号文本,其字面由覆盖字形绘制(描边薄于 2 个设备像素时不提示),而这些效果由距离场绘制,并与之一一对应(SmallTextEffectFace Auto;Field 让此类文本完全留在距离场上)。
  • 渲染层内的小字号文本,在层静止 3 帧后由覆盖字形绘制,移动期间由距离场绘制。
  • 字面柔度和膨胀可让文本保持在距离场上。
  • 一个文本可以通过 SmallTextRaster = Off 在任何字号下都留在距离场上;一个字体有自己的 SmallTextCoverage、 SmallTextMaxPixelSize 和 CoverageHinting。
  • SmallTextContrast(默认 1)设置覆盖字形的对比度;bSmallTextCorrection(开启)让这些字号下仍从距离场绘制的文本变暗。一个世界每帧最多将 SmallTextRepaintBudgetPerFrame(512)个文本重绘到覆盖字形上。
  • 只要有文本从覆盖字形绘制,字体就会保留这些字形的图集单元格。超过两倍 MaxCoverageCells(在 项目设置 > 插件 > DreamUI 中默认为 4)后,新的小字号字形会排队等待,期间由距离场绘制,每个字体只警告一次。
  • 不通过 MF_DreamUI_Shade 着色的自定义材质不会获得覆盖字形。

富文本

开启 bRichText 后,文本中的标签生效;RichTextTagFilterFlags 决定解析哪些种类(Bold、 Italic、Underline、Strikethrough、Size、Color、Superscript、Subscript、CustomTag、Image、Hyperlink、 Language、Gradient),被过滤掉的标签会当作普通文字显示(例如关闭 Language 标志时的 <lang>)。标签包括 <b>、<u>、<s>、<size=40>、<color=…>、<sup> / <sub>、行内图片 <img=Tag/>(可选带尺寸和 baseline 或 top 之类的对齐词)、可点击的 <a=Id>(OnHyperlinkClickedBP)、<lang=ja> (其包裹的内容按该语言选择回退字体和字形),以及下一节的 <gradient=Name>。字面的 < 写作 &lt;。

自定义标签和样式来自 RichTextCustomStyleData(UDreamUIRichTextCustomStyleData),行内图片来自 RichTextImageData。控件库里的 UDreamRichTextBlock 是对应 UMG RichTextBlock 的控件。

渐变文字

文本的字面、描边,以及叠在字面上的一层,各自可以用渐变来绘制。三层都在 FDreamTextStyle 上——FacePaint、OutlinePaint、OverlayPaint——每层是一个 FDreamTextPaint(bEnabled、共享的 Preset,或自带的 Gradient)。

  • 种类:Linear、Radial(椭圆按 Angle 旋转)、Conic、Diamond、Reflected(对称:从过中心的一条线向两边展开)和 Corners(四角色,TextMeshPro 的那种),最多 16 个色标;超出两端时 Pad、Repeat 或 Reflect;在 sRGB、线性光或 Oklab 里混色。 RectBlock 的主体和描边用的也是这种渐变(见渐变与视口手柄)。
  • 按 CSS 的写法写:linear-gradient(180deg, #FFF3B0, #E8B64A 55%, #9C6A12),可写在细节面板、 .dui 中,或作为富文本的一段。按 Chrome 的方式读取,只有两点不同:to <corner> 无论盒子什么形状都取正方形的角度,颜色名是 CSS 的(green 是 #008000,而 <color=green> 是 #00FF00)。
  • 量在什么上:PaintBoxHorizontal / PaintBoxVertical 分轴选择 TextBlock、ContentBox、Line、 Glyph 或 Run。
  • 字面渐变替代文本自己的颜色,就像 CSS 的 background-clip: text 那样;其中的 <color> 段是纯色。叠加层通过 OverlayBlend(Normal、Add)混到字面上。
  • 预设:UDreamGradientAsset 资产,或项目设置里按名字存的 CSS 字符串(GradientPresets)。用同一个渐变的文本在 GPU 上共享一行。
  • 富文本:<gradient=Name>…</gradient>,名字依次查自定义样式条目、项目预设,然后按去掉空格的 CSS 读取。Gradient 是新加的过滤位:其 RichTextTagFilterFlags 保存为不含该位的掩码的文本,会把标签当文字显示。

渐变的相位、角度、中心和缩放可以动画,而不重新布局文本、也不重绘文本——每次改动只写文本 paint 表里的一个像素。FacePaintPhase、OutlinePaintPhase、OverlayPaintPhase 和 PaintAngleOffset 可在 Sequencer 里打关键帧,UDreamTextPaintLibrary 用 PaintPhaseTo、PaintAngleTo 和 PlayShimmer 对它们做补间:

#include "Core/Text/DreamTextPaintLibrary.h"

// Title is a UDreamText*
FDreamTextPaint Face;
Face.bEnabled = true;
FDreamGradient::ParseCss(TEXT("linear-gradient(180deg, #FFF3B0, #E8B64A 55%, #9C6A12)"), Face.Gradient);
Title->SetFacePaint(Face);

// A band transparent at both ends, added onto the face: a shimmer
FDreamTextPaint Band;
Band.bEnabled = true;
FDreamGradient::ParseCss(TEXT("linear-gradient(90deg, transparent 40%, white 50%, transparent 60%)"), Band.Gradient);
Title->SetOverlayPaint(Band);
Title->SetOverlayBlend(EDreamTextOverlayBlend::Add);

UDreamTextPaintLibrary::PlayShimmer(Title, 1.2f, 0.0f, -1);   // 1.2 s a pass, until stopped

不通过 MF_DreamUI_Shade 着色的材质改用顶点色绘制渐变(此时动画会触发重绘)。

按文化断行

断行和分词迭代器按游戏当前的文化创建,文化变化时重建(2.0 跟随的是操作系统的语言)。

  • 带 CJK 文本的游戏必须连同对应的 ICU 数据一起打包(EFIGSCJK 预设;泰语及其邻近语言用 All)。
  • 编辑器里,DreamGUI 自己的那份 ICU 被指向引擎的 ICU 数据(Engine/Content/Internationalization),因此编辑器与打包后的游戏一样按游戏文化断行;读不到数据时日志只说一次,改由引擎默认文化的迭代器顶替。
  • PhraseWrap = CJKDictionary 换行时用 ICU 的词典把 CJK 词语保持在一起(CSS 的 word-break: auto-phrase)。它只在 VerticalOverflow 时才有意义,且需要打包的 ICU 数据包含 CJK 词典;否则会悄悄退回逐字断行。
  • Language 是文本书写所用的语言("ja"、"zh-Hans"、"en-US"):优先使用为它准备的回退字体,HarfBuzz 也按语言选脚本的字形(locl)。留空表示游戏当前语言;富文本的 <lang=xx> 覆盖它。断行始终跟随游戏文化,不管这里写什么。

增量布局

主动要求增量布局的文本(正在被输入的文本框),或长文本(256 个元素以上)在连续两次布局中内容都发生变化时,会保留上次布局找到的结果,只重新布局编辑触及的部分:在长段落里,只有编辑点周围的一个窗口被重新整形和测量,再拼回其余部分;显示列表也在原处编辑,而不是整个重写。以前整形过的词——字面、字号、书写系统、方向、语言和特性都相同——会从整形缓存中取用,不再重新整形。

增量布局和同一文本的全新布局,结果逐个元素完全相同;下面的开关只是拿时间做交换。编辑落在以标点、数字或 emoji 开头的长段落开头附近,或者紧跟在行内图片之后时,按整段的方式整形。

控制台变量

变量默认作用
DreamGUI.Text.SmallTextCoverage-1-1 跟随项目设置;0 对所有字体关掉覆盖字形,包括设为 On 的;1 对所有交给项目决定的字体打开。改动会重绘所有文本
DreamGUI.Text.SmallTextMaxPixelSize0大于 0 时,替换所有没有自己上限的字体的 SmallTextMaxPixelSize —— 用来把覆盖字形强加到更大的标签上做测量
DreamGUI.Text.SmallTextOnMove0用覆盖字形画的小字移出像素网格时:0 每次移动都从覆盖字形重绘;1 移动时保留覆盖四边形、静止 3 帧后重绘;2 先从距离场重绘一次,静止 3 帧后再回到覆盖字形
DreamGUI.Text.IncrementalLayout10:每次布局都从零开始,什么也不保留
DreamGUI.Text.IncrementalParse10:每个元素都重新读
DreamGUI.Text.IncrementalMeasure10:被编辑的段落整段测量(需要 IncrementalParse)
DreamGUI.Text.InPlaceDisplayList10:显示列表整个重写
DreamGUI.Text.VerifyIncremental01:每个基于保留结果的布局都再从零做一遍并比较,记下第一处差异、改用新结果。用来找增量布局的错,Shipping 构建里没有
DreamGUI.Text.ShapeCache10:每段都整个整形,不用缓存
DreamGUI.Text.ShapeCacheKB4096整形缓存的预算,单位 KB;4096 约能放 15,000 个词,最久未用的先走。改动会清空缓存
DreamGUI.Text.ShapeCacheFlush命令清空整形缓存;计数保留

另有两个开关在测量出结论之前默认关着:项目设置 bFieldTextCorrection(SmallTextMaxPixelSize 以上的距离场文本也用小字的对比度和线性光混合,免得字重在分界处跳变),和控制台变量 DreamGUI.Scroll.SnapToDevicePixels(2D 画布上的滚动视图按整设备像素移动内容)。DreamGUI.Memory 列出每个字体的字形图集——切片、GPU 字节和 CPU 拷贝、格子、字形、字面字节。

本页目录