Skip to content
SFML.js

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: 20dp40 个物理像素,保持视觉尺寸
font-size: 20px20 个物理像素
鼠标输入直接转发,不再乘以缩放比例

上下文在更新时刷新 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 布局、字形栅格化、命中测试、尺寸变化、物理像素截图和尺寸限制。跨物理显示器移动窗口仍需设备测试。

Icons made by Lorc, Delapouite & Skoll game-icons.net · CC BY 3.0