禁止商用。所有使用 PolarisUI 的应用都必须公开完整源码。查看许可条款

2.4.1 替换注意

新的库、示例 JAR 已包含 matching native 和 shader。替换时不要保留 2.4 的 DLL 或单独从旧包覆盖 geometry.glsl。出现协议不匹配请核对是否混用了版本，而不是绕过校验。

Sidebar 现在默认无单独底板；需要独立面板外观可显式调用 glass(true)。普通 ListBox 默认仍带表面；嵌入父玻璃面板时可用 glass(false)。

Panel 默认按自身轮廓裁剪子内容。原先故意把 child 放到 Panel 外面的位置，应显式 clipChildren(false) 或使用 Ui 管理的 popup 层；不要靠放大 scissor 偶然越界。

常见问题

文本发软或字体路径切换

默认 AUTO 在小字号静止状态使用实际 DPI 灰度覆盖，大字和明显缩放使用 SDF。宿主应在绘制前调用四参数 painter.begin(uiWidth, uiHeight, pixelWidth, pixelHeight)；只在 flush 时补物理尺寸无法为第一帧正确选择 DPI 字形。pixelSnap 对齐静止文本起点和基线，不会对动画整体位置强行逐像素跳动。SDF 不保证在极小字号比原生 hinting 更好；参数含义见 FONTS.md。

新旧 native 混用

2.4 的指令步长为 64 float，启动时检查协议 24064。出现协议不匹配时说明加载了不匹配的旧 native，而不是 GLSL 自动降级。使用同一开发包内匹配的 Java 与 native；不要从 2.3 单独复制 DLL。

JAR 没有 main

jdk8/lib/liquidglass-ui-jdk8.jar 和 jdk21/lib/liquidglass-ui-jdk21.jar 是库，没有展示入口。可直接启动的是相应 jdk8/demo/ 或 jdk21/demo/ 下的 demo JAR；每个目标目录有独立启动脚本。

Windows WGL 错误

代码保留固定 HDC 和已验证 context 回退。新库的图形控件层不会自行更换窗口 pixel format。使用 run-demo.cmd 会显式关闭 Java2D OpenGL/D3D 管线，Main 入口中的 DesktopWindow 也在 AWT 初始化前设置相同属性。

出现问题时 liquidglass-ui.log 中的具体 WGL 阶段和 GetLastError 比统一的“需要 Java 8/OpenGL 3.3”提示更有诊断价值。Windows 实机尚未验证，不能仅凭 Java 版本和显卡型号断言问题一定在用户驱动或一定已被修复。

平台或 JAWT 缺失

内置 native 只支持 x64 Windows/Linux。Java 架构需要 amd64/x86_64，而不是 x86/ARM。查找 JAWT 的路径来自 java.home；headless-only JRE 可能没有相应文件。Linux 窗口需要实际 X11/XWayland 会话；自动测试可使用 Xvfb。

没有显著模糊

没有细节的纯色或平滑背景很难观察模糊。概览中的材质开关控制 sigma，启动 --grid 可以查看背景网格变柔和的变化。测试使用高频棋盘纹理定量验证了两遍 Gaussian 的作用。

文字清晰是预期行为：它绘制在相应控件表面之后。弹窗会捕获其下面已经画好的界面，所以底层文字在弹窗玻璃里可能变模糊，而弹窗自身文字仍清晰。

部分符号显示方框

库不附带字体。优先选系统 Microsoft YaHei / Noto Sans CJK SC 等，缺字再尝试系统 Dialog 字体。如果系统没有能显示某个字符的字体，不能保证全部符号有字形。这不同于 shader 渲染失败。

宿主的 context / framebuffer

attachCurrentContext() 需要已经 current 的 OpenGL 3.3+ context，而且始终在该线程上调用。flush 接收 framebuffer ID，不是 texture ID。MSAA 输入先 resolve；库会暂时停用 depth/stencil 并恢复，不利用宿主 stencil 裁剪。

一次挂接关闭后可以重新创建；同一时间多个 NativeBackend 会被拒绝。关闭 Painter 和 Backend 时 context 必须仍然有效。

事件无响应

既要绘制 Ui，也要把输入转换成 UiEvent 送入 ui.input。鼠标坐标为逻辑 UI 左上角坐标，不是 framebuffer 物理像素。文字输入使用 TEXT 事件，按键导航使用 KEY 事件，二者不要混为一谈。

回调和控件更新属于 Ui 线程。文件加载或网络工作线程通过 ui.post 回到 UI；本库不会替宿主建立网络访问或业务线程模型。