LiquidGlass UI SDK 2.4.5

许可：禁止商用；所有使用 PolarisUI 的应用都必须公开完整源码。 当前采用自定义非商业源码许可，不是 MIT。完整条款见 LICENSE 和 许可说明；此前合法授予的旧版 MIT 权利不被追溯撤销。

包名已迁移至 polaris.sdk.ui；控件、渲染和场景示例分别位于 .controls、.render、.samples。旧的 dev.liquidglass.ui 导入需更新并重新编译，旧包名的二进制不兼容。JAR 文件名保持不变。随包 JNI 库与新包名配套，不要与旧版混用。

已构建的 Java 8 和 Java 21 双目标开发包。保留原来的 68 类控件、WGL 修复、黑白材质、受控反光、较强背景模糊、横向微调器和控件动画；保留 2.4 中已实现的全局抗锯齿、改进文本渲染、四角独立三次贝塞尔轮廓和可配置主题颜色。

解压后打开 index.html，可离线进入中文文档、Javadoc、控件目录和完整示例。

2.4.5：Morden / LiquidGlass / Normal 材质模板

每页右上角 LiquidGlass 设置 → 材质模板 增加三个按钮。名称按请求保留为 Morden（不擅自改拼写）、LiquidGlass、Normal。一次点击同步设置全部八个数值，滑杆和横向加减编辑器即时更新。

Normal 按给定数值保留高光 1.5，不因为名称而额外关掉高光。sigma=0 时背景模糊开关同步显示关闭。选择任一模板后仍可继续单项调整；再次点模板会覆盖恢复这八项值。

模板只改材质，不替换配色、字体、四角参数、AA、动画或网格状态。不改变启动默认值，原有“通透 / 柔和 / 低反光 / 恢复默认”仍保留。新增模板行在窄面板自动换行，与原参数采用相同留白和 gap。

开发 API：MaterialPreset.MORDEN.applyTo(ui.theme())；也可通过设置面板的 applyPreset(MaterialPreset.LIQUID_GLASS) 调用。完整可运行示例为 examples/MaterialPresets.java，详见 材质模板。

2.4.4：场景示例分类（保留）

展示程序左侧新增 场景示例（第十页），里面不是单个按钮排成控件目录，而是把已有控件组合成六种完整的日常应用界面：外卖点餐、即时聊天、外挂风格客户端面板、音乐播放、系统设置、文件管理。

每个场景都有真实的本地状态和交互。购物袋会计算数量、优惠和运费；聊天支持切换会话、保留草稿、发送和本地自动回复；客户端面板支持模块分类、搜索、开关、参数、按键和快照；其他场景也有各自的操作流程。切换场景或离开此分类后再回来，状态不会被重建清空；关闭整个展示窗口后不保存。

右上角 LiquidGlass 设置依然可用。 模糊、高光、色散、折射、tint、网格和背景动画与其他页面共用同一套设置；这次没有改动底层 shader、native、字体、动画或圆角裁剪实现。

这些都是组合控件示例，不连接外部服务：不真实下单/付款，不联网聊天，不注入游戏或执行外挂功能；播放器模拟进度与操作但不输出音频；文件管理只操作内存中的虚拟目录，不读取、写入或删除磁盘文件。

可以直接进入某个场景：

java -jar jdk8/demo/liquidglass-ui-demo-jdk8.jar --scene=food
java -jar jdk21/demo/liquidglass-ui-demo-jdk21.jar --scene=chat
java -jar jdk21/demo/liquidglass-ui-demo-jdk21.jar --scene=client --grid

可选值是 food、chat、client、music、settings、files；原来的 --page=0..8 不变，--page=9 对应新增分类。Ctrl+K 命令面板也能直接跳转这些场景。

六个组合界面的完整实现放在 src/main/java/polaris/sdk/ui/samples/，也包含在 library 与 source JAR 中，可直接作为宿主控件使用。本包当前共 21 个完整示例入口/接入源文件，包括七个新增的场景独立运行入口。功能、示例路径及复用方式见 场景示例文档。

2.4.3：高光与 RGB 色散修复（保持不变）

高光默认 shine=.82，色散默认 dispersion=.85，两者都已开启。每页右上角的 LiquidGlass 设置 可独立调整，也可分别设为 0 关闭。色散依然不改变默认黑白灰配色；彩边只由背景通道采样差产生，不是额外描边或彩色覆盖板。

反射沿原有贝塞尔/SDF 轮廓出现，峰值仍在 d=0，浅色玻璃通过相反方向的环境反射保留边缘对比。强度有界，鼠标经过中心不会翻转光照，也不把整块控件刷白。

色散改为从同一帧清晰背景提取局部通道差，再把色度差混入已模糊的玻璃。默认 sigma 18 / 混合 .98 保留，即使 sigma 32 / 混合 1，色散也不再被整块高斯模糊抹掉；玻璃中间的明暗细节仍保持模糊。均匀背景上不会凭空生成彩虹边。

“通透”“柔和”“低反光”和“恢复默认”不再把色散统一设为 0。“低反光”现在是独立预设，不再与“恢复默认”重复。模型、滑杆和横向数值编辑器保持同步，切换页面或深浅色不清空已调参数。

新增完整示例 OpticsComparison：在同样的背景与模糊下并排查看关闭、高光单独、色散单独、两者开启四种情况。运行 run-example.cmd 8 OpticsComparison 或 sh run-example.sh 21 OpticsComparison。着色器实现、量纲和测试见 高光与色散修复。

这次未修改 Java/native 命令协议、WGL 生命周期、字体、动画和圆角裁剪算法；原有 68 类控件全部保留。

2.4.2：实时材质设置与网格背景（保留）

展示程序每页右上角新增 LiquidGlass 设置，完整提供 Gaussian sigma、模糊混合、折射强度、高光、色散、tint、不透明度和选中 tint 调整。设置中的网格开关实际控制 GPU 背景，菜单“显示网格”也接回了同一状态，不再只有日志。

滑杆、横向数值输入和 API 使用同一模型；切换分类、关闭重开设置窗口或切换深浅色不重置材质参数。原有间距/嵌套圆角裁剪保持修复，额外底板、强白边没有恢复。

启动时直接打开：java -jar jdk8/demo/liquidglass-ui-demo-jdk8.jar --material-settings --grid。Java 21 使用同目录结构下的 jdk21 版本。

原折射 shader 的提前限幅造成大半滑杆无变化；新版本改为连续且有界的采样位移响应。这里的值是屏幕空间强度，并不假装是物理 IOR。详情、API 及完整示例见 实时材质设置。

新增可复用 GlassSettingsPanel / GlassSettingsDialog，以及 Ui.background() 的实时网格与暂停控制。全局颜色、AA、文字和圆角设置保留。未改动 native 协议或 WGL 代码。

2.4.1：间距与嵌套圆角裁剪修复

本包实际修复了 2.4 中的列表左右不对称、无滚动条仍保留空槽、侧边栏重复底板，以及子内容仅按矩形剪裁的问题。它不是只调整截图，也不是在界面上新增一层着色遮罩。

Sidebar 默认只绘制选中项的玻璃，不再绘制额外的整块底板。ListBox 仍可以作为独立列表使用；需要嵌入现有玻璃容器时可调用 glass(false)。列表绘制、命中、滚动边界共用同一套 padding 和行范围；隐藏滚动条时归还宽度。

Panel 默认启用子内容裁剪，轮廓与自身表面的四角贝塞尔/圆角参数完全相同。填充、玻璃、文字、圆环、线段和颜色平面均参与 GPU 裁剪。多个父级轮廓取交集；动画中的轮廓也使用同一变换。父级 viewport 不再随子按钮按压被错误缩小。控件自身的边缘反光不会作为“内容”再裁一次。

旧 API 和两个 Java 目标保留。新增绘制接口、兼容性及限制见 裁剪修复说明。替换版本时使用本包完整的库/示例 JAR；Java、GLSL 和 native 协议已一起更新，不能混入旧 DLL 或旧 shader。

选择运行版本

Java 8 目标：引用 jdk8/lib/liquidglass-ui-jdk8.jar。使用 jdk8/run-demo.cmd 或 sh jdk8/run-demo.sh 运行展示。

Java 21 目标：引用 jdk21/lib/liquidglass-ui-jdk21.jar。使用 jdk21/run-demo.cmd 或 sh jdk21/run-demo.sh 运行展示。

两个版本分别编译为 class major 52 / 65。Java 21 版最低要求 Java 21；Java 8 版可在 Java 8 及更新版本运行。两者使用相同源码和公开 API，不要在同一 classpath 中同时放入两个版本或同时放入 library 和 demo JAR。

独立演示内置 Windows x64 / Linux x64 native 和 GLSL，无须联网、Maven 或 LWJGL 下载。仍需要本机桌面 Java 运行时及 OpenGL 3.3+；本包不附带 JRE。

保留的 2.4 绘制能力

文本：小字号静态文本不再固定把三倍图集缩小采样，而是按实际 framebuffer DPI 缓存灰度覆盖字形，并对齐文本起点和基线。大字号及较明显的缩放可以使用真实的单通道 SDF 字形图集；GPU 依据导数重建边缘。可切换 AUTO / COVERAGE / SDF，调节文字对比度、字距、字体族和像素对齐。

全局抗锯齿：Antialiasing.OFF / ANALYTIC / HIGH 统一控制内置 UI 几何与文本边缘。HIGH 对 SDF 覆盖使用四个子像素样本，不是给最终画面加 FXAA 或整屏模糊，也不是宣称硬件 4×MSAA。宿主原有 3D 场景不受它自动管理。

圆角：普通圆角矩形可以由四条三次贝塞尔曲线和四条直线组成，每个角独立配置半径及曲线形状。GPU 计算到三次曲线的数值最近点距离；玻璃、描边、边缘光和填充共用该轮廓。不是把圆弧 SDF 改名为 Bezier。圆形滑块、头像和胶囊默认保持圆形特征，显式角配置可以覆盖。

配色：背景、玻璃 tint 色、文字、次要文字、强调色、强调色上的文字、边缘高光、边缘阴影、选择色和语义色都可配置。默认仍是黑白灰；不会强制变回蓝白。状态变化继续直接改变材质参数，不增加选中描边或覆盖底板。

这是屏幕空间材质，不是 Apple 原生组件的源码复刻。单通道 SDF 不等于 MSDF；四段三次曲线也不被描述为 Apple 的私有连续圆角算法。

最小代码

下面代码也是包内示例 API 的真实用法：

import polaris.sdk.ui.*;
import polaris.sdk.ui.controls.*;

public final class Hello {
    public static void main(String[] args) throws Exception {
        DesktopWindow.run("LiquidGlass 2.4", 1080, 740, ui -> {
            ui.theme()
                .antialiasing(Antialiasing.HIGH)
                .textMode(TextMode.AUTO)
                .pixelSnap(true)
                .accent(Colors.hex("#DADADA"))
                .highlight(Colors.WHITE);

            Button button = new Button("四角独立的按钮");
            button.bounds(40, 50, 280, 70);
            button.radius(16, 24, 10, 18);
            button.corner(Corner.TOP_LEFT, new BezierCorner(22, 0.8f));
            button.onClick(w -> ui.notify("完成", "SDF、文字和动画均已接入"));
            ui.root().add(button);
        });
    }
}

控件的通用 setter 仍返回 Widget，专用 setter 返回各自类型；如上保留有具体类型的变量即可。坐标和半径使用父级局部逻辑单位，sigma 使用实际像素。更多完整代码见 示例。

文档和内容

src/main/java/：完整控件、布局、事件、字体、绘制指令和展示源码。

resources/shaders/：玻璃、Gaussian blur、共用三次曲线距离函数、SDF/覆盖字体和图元 shader。

native/：C/JNI、WGL/GLX 源码与重建脚本。Windows context 生命周期机制沿用之前修复。

examples/：21 个完整入口/接入源文件。新增 MaterialPresets 模板示例；保留六个独立应用场景、合集入口以及材质、光学对照、AA、曲线、主题、宿主、自定义控件等全部示例。src/main/java/polaris/sdk/ui/samples/ 是这些应用的实际控件组合与模型实现，不是静态图片。

docs/javadoc/：从当前真实源码生成的离线类/构造函数/方法索引。同一套 API 文档适用于两个目标。各目标 lib/ 另有源码 JAR 和 Javadoc JAR，可关联到 IDE。

tests/：旧功能回归、新 API、实际 GPU 像素检查与真实窗口交互测试。本次实际运行记录在 tests/results/2.4.5/，旧版记录另行保留。

离线构建

JDK 21 环境中运行：

sh build.sh all
sh build-docs.sh

Windows 对应：

build.cmd all
build-docs.cmd

只重建 Java 8 目标：build.cmd 8 或 sh build.sh 8。本机是真正的 JDK 8 时也可使用这条路径。只重建 Java 21 目标：build.cmd 21，需要本机 JDK 21+。

默认不传目标时，JDK 21+ 构建两版，较老 JDK 构建 Java 8 版。此构建只需要 JDK，不要求 Maven、Gradle、Python 或 C 编译器；预编译 native 已包含在资源中。只有修改 C 代码才需要原生工具链。

直接运行完整示例

run-example.cmd 8 RenderingQuality
run-example.cmd 21 BezierCorners
run-example.cmd 21 CustomPalette

Linux 命令是 sh run-example.sh 8 RenderingQuality 等。脚本会先将示例编译到对应目标目录，再引用同包的 library JAR 运行。Main 是默认最小示例；HostIntegration 是宿主接入类，没有单独的 main。

展示程序保留第九页“绘制与配色”，新增第十页“场景示例”。可实时切换 AA、字体路径、像素对齐，拖动贝塞尔参数，修改颜色。

java -jar jdk21/demo/liquidglass-ui-demo-jdk21.jar --page=8
java -jar jdk8/demo/liquidglass-ui-demo-jdk8.jar --aa=HIGH --text=AUTO

运行范围与验证

发布 class 已分别检查为 52 / 65；实际运行虚拟机为 OpenJDK 21。图形测试使用 Linux Mesa llvmpipe 的 OpenGL 3.3 Core / Compatibility。Windows x64 DLL 沿用 2.4.1 已交叉编译的版本，本次再次检查 JNI 导出，但没有 Windows 实机测试，也没有真正的 JDK 8 VM 或独立显卡性能测试。

字体使用本机安装字体，不捆绑字体文件。Linux native 需要 X11/XWayland、libGL、libX11 和 glibc 2.34+；较老系统可以重编 native。当前预编译包没有 macOS、ARM 或 32 位 native。

现有复杂文字 shaping、HDR、透明背景合成、软换行、多列级联菜单和无障碍桥接等限制没有被这次更新自动解决。具体范围及本次实际测试见 限制 和 测试报告。