RmlUi 渲染与 Retina
RmlUi 布局和几何数据保留在原生后端,由 SFML 管理顶点缓冲、纹理、着色器和渲染目标。运行时整个生命周期内使用同一个已打开的 RenderWindow。
创建渲染器要求 SFML 支持着色器,且六个必需程序全部编译成功。 缺少支持或编译失败会在注册、选择接口前抛出异常。几何或裁剪掩码上传失败时, 当前 UI 帧中止并恢复宿主视图。仅合批缓冲区分配失败时,逐个绘制保持原提交顺序。
合成一帧
清空窗口,录制 SFML 场景,调用 window.flush(),渲染 RmlUi 上下文,最后调用 window.display()。flush 确保场景命令在 UI 前提交。绘制前调用 context.update(),应用布局、动画和显示密度变化。
每次 context.render() 使用透明的 UI 基础图层,遍历成功后将它合成到宿主场景。成功或失败都会恢复宿主 View 和适配器状态;回调异常会丢弃当前 UI 帧。渲染回调读取窗口时看到已提交的宿主场景,UI 像素在该帧完成后才写入窗口。
上下文帧和离屏图层自带经过验证的八位模板缓冲。在上下文帧之外使用 RenderManager 直接绘制窗口时,需要设置 settings.stencilBits: 8。
图层零可作为合成源或目标,支持自合成和透明度遮罩快照。在上下文帧内,它只包含 RmlUi 内容;帧外的管理器操作将宿主窗口作为图层零。备用池最多保留八个尺寸匹配的图层,存储预算为 32 MiB;尺寸变化时释放旧尺寸图层。
物理像素与 dp
macOS 上,initialise(window) 在保持窗口屏幕尺寸的同时启用原生 Retina 表面。此后窗口尺寸、鼠标/尺寸事件和纹理截图均使用物理像素。应在初始化之后通过 window.getSize() 创建上下文。
| 密度为 2 时 | 结果 |
|---|---|
| 屏幕上的 1024 × 768 窗口 | 2048 × 1536 帧缓冲和上下文 |
font-size: 20dp | 40 个物理像素,保持视觉尺寸 |
font-size: 20px | 20 个物理像素 |
| 鼠标输入 | 直接转发,不再乘以缩放比例 |
上下文在更新时刷新 densityIndependentPixelRatio,processEvent 处理尺寸变化。context.dimensions 是缓存的只读视图;使用 setDimensions(width, height) 更新原生布局。
initialise(window, { highDpi: false }) 保持已有表面状态,包括已经启用的表面。一旦启用,将持续到窗口关闭,shutdown() 不会关闭该表面。其他平台使用后端报告的密度,当前为 1。
渲染支持范围
视口、矩形裁剪、自有几何蒙版、矩阵提交与状态保存恢复见 渲染状态。
| 功能 | 当前支持 |
|---|---|
| 文字、纹理、纯色几何和矩形裁剪 | 已实现 |
| 模板裁剪遮罩和圆角溢出裁剪 | 已实现,需模板缓冲 |
| 离屏图层与合成 | 通过 SFML RenderTexture 实现 |
| 模糊与投影 | 通过 SFML Shader 实现 |
| 图层透明度快照蒙版 | 已实现,保留裁剪区域的原视口位置 |
| 线性、径向、圆锥、重复渐变及 creation | 原生程序,保留全部停靠点和齐次变换 |
| CSS 图片遮罩 | 已实现;macOS 的前景/背景/遮罩组合已与 GL3 对照验证 |
| 透明度、亮度、对比度、反相、灰度、褐色、色相旋转、饱和度 | 通过原生预乘颜色着色器实现 |
| 背景滤镜 | macOS 已验证可读取的 UI 基础图层和组合 CSS 效果 |
| 几何与裁剪的 4×4 变换 | 原生齐次投影、Z 裁剪和透视纹理插值 |
VisualTests 启动器用于预览上游页面。加载无崩溃不代表视觉断言通过,也不代表完整覆盖 RmlUi 渲染能力。
颜色滤镜按列表顺序执行。RenderManager.compileFilter(name, { value }) 使用原生名称 opacity、brightness、contrast、invert、grayscale、 sepia、hue-rotate 和 saturate;色相角度使用弧度。省略数值时默认为 1, 显式数值必须是有限数字。颜色矩阵保留预乘透明度和透明像素, 反相与透明度限制在 0–1。与固定版本 GL3 一致,矩阵输出按 RGBA8 通道范围截断, 不会截到源透明度。加载、生成、预加载和保存图层所得的普通纹理均使用线性过滤与 重复寻址,UV 超出 0–1 时也会重复。效果着色器不可用时,编译返回无效句柄。
blur 使用 { sigma },默认值为 1,必须是有限的非负物理像素数。 大半径采用固定版本 GL3 的逐级二分缩放和七点高斯核,再按二次幂稳定定位。 当前矩形裁剪范围外的采样贡献透明像素;缩小后没有剩余采样的区域输出透明。
drop-shadow 使用 { sigma, offset, color },默认 sigma 为 0, offset 为 { x: 0, y: 0 },颜色为不透明黑色。偏移必须是有限的物理像素数, 正 Y 方向向下;颜色使用非预乘 RGBA 字节。着色器先偏移、着色源透明度, 再按需模糊(sigma ≥ 0.5),最后将完整源图像叠在阴影上。 滤镜链按顺序执行,复用三个 SFML 中间目标,保留预乘像素和源图层。 macOS 原生套件对照官方固定版本 GL3 的 16 个奇数尺寸、全窗口/裁剪截图, 并验证透明边界、源图层保留、小数/负向偏移和资源复用。
十个真实 RML/CSS 场景覆盖前景滤镜、背景滤镜、渐变遮罩、全部组合和变换圆角 溢出裁剪。macOS 的 GL3/SFML 最大 RGB 通道误差为 1,平均误差小于 0.004。 重复帧和逆序场景保持完全相同的 SFML 像素,并检查预乘透明度和透明角落。 十二组原生分配测试覆盖基础层、图层、中间目标、捕获的失败与重试;遮罩记录 分配失败时会释放已捕获纹理。完整应用和 VisualTests 的验收单独进行。
几何与裁剪蒙版共用完整的列主序矩阵。几何平移先于矩阵变换,投影使用左上角 物理像素坐标,Z 范围为 −10000 到 10000。蒙版保留定义时的矩形写入范围与变换 快照;交集对重叠三角形保持布尔语义,并在八位模板计数耗尽前归一化。 自定义 vertex_shader 扩展继续使用用户提供的顶点程序及 SFML 仿射变换约定。
渐变与 creation 参数
RenderManager.compileShader 的 linear-gradient 使用 p0、p1, radial-gradient 使用 center 和正数 radius,conic-gradient 使用 center 和弧度 angle。它们使用局部像素 UV、默认 false 的 repeating, 以及带类型标签的 color_stop_list。位置必须是有限、非递减的 Unit.NUMBER 数值,颜色字节已预乘透明度。所有停靠点按 GL3 的逐段 smoothstep 混合, 超过 16 个也全部保留。完整列表写入专用 GLSL 程序;GPU 编译失败时资源无效。
单个停靠点绘制纯色。位置重合时在该位置切换到后一个颜色。重复范围由首尾位置 确定,范围为零时绘制最后一个颜色。空列表、降序位置、重合的线性端点、 非正径向半径或非有限参数均返回无效资源。圆锥中心的渐变坐标为零。
creation 使用名称 shader 和 { value: 'creation', dimensions: { x, y } }, 尺寸必须为有限正数。它使用局部归一化 UV 和 SystemInterface 的经过秒数, 保留固定版本 GL3 的 RGB 公式及顶点透明度。中心距离及倒数分母的下限为 1e-6, 避免非有限像素。内置效果使用完整 4×4 变换并忽略可选纹理。 显式提供 vertex_shader、fragment_shader 时使用自定义 GLSL 扩展及 SFML 仿射坐标约定。
验证显示密度
在 packages/sfml.js-rmlui 执行 npm test;macOS 另执行 npm --prefix ../sfml.js-interop run test:high-dpi。回归覆盖 1×/Retina 布局、字形栅格化、命中测试、尺寸变化、物理像素截图和尺寸限制。跨物理显示器移动窗口仍需设备测试。