C++ 控件与渲染 API

公开接口以 ui.hpp 为准，命名空间 polaris::ui，要求 C++17。

创建一帧

窗口和渲染器构造顺序为 Window、Renderer、Canvas、Ui。保持窗口的 OpenGL 上下文 current，先调用 Window::poll()，再依次调用 Renderer::begin()、背景绘制、Ui::begin()、控件、Ui::end()、Renderer::render() 和 Window::swap()。完整代码见 hello.cpp。

窗口宽高是客户区物理像素，dpi_scale() 将它们换成逻辑尺寸。控件和鼠标坐标均使用逻辑像素。Input::pressed / released 只对一次 poll 有效，down 保持鼠标按住状态。poll() 为 false 后停止循环。

交互控件

方法	值/返回	行为
`label`、`panel`	不返回状态	文字、可选玻璃背景与标题
`button`	返回本帧激活	按下捕获，范围内释放或 Enter 激活
`checkbox`、`toggle`	`bool&`，返回值变化	开关布尔状态
`radio`	`int&`，返回选项变化	选中指定整数选项
`slider`	`float&`，返回值变化	拖拽捕获、上下限、焦点方向键
`text_field`	UTF-8 `string&`	单行文字、码点级编辑和粘贴
`number_field`	`float&`	+/- 步进，有限范围
`combo`	`int&`	弹出选择、滚动，最多同时显示 8 项
`tabs`	`int&`	横向选项导航
`list`	`int&`	单选、滚轮、裁剪
`progress`、`separator`、`badge`	不返回状态	进度、分隔与状态文字
`tooltip`	不返回状态	指针命中时显示提示
`material_settings`	`Theme&`	8 参数滑块、3 材质模板与贝塞尔开关

ID 不能为空、同帧不能重复，且跨帧须稳定。disabled(true) 影响随后绘制的控件，直到 disabled(false) 或下一次 begin()。Tab / Shift+Tab 按上一帧的调用顺序切换焦点；不可见和禁用控件不保留焦点。下拉弹层使用独立绘制阶段，并阻止其他控件响应同一轮点击。

材质参数

字段	范围	含义
`tint`	0–1	表面颜色混合；0 不染色
`blur`	0–1	清晰/模糊背景混合；0 不模糊
`sigma`	0–32	物理像素高斯半径；0 跳过模糊 pass
`refraction`	0–30	屏幕空间边缘偏移，不是物理折射率
`shine`	0–1.5	边缘高光强度
`dispersion`	0–2	RGB 通道采样分离
`surface_opacity`	0–1	表面覆盖透明度
`corner_smoothing`	0–1	归一化贝塞尔圆角手柄

Theme::light() 返回浅色默认主题，Theme::liquid() 返回零染色/零模糊折射主题，Theme::normal() 返回不折射的实色材质。修改字段后 validate() 可提前检查；绘制也检查范围与 NaN。

Canvas::glass(rect, material) 可使用不同的面材质，但模糊半径由本帧 Renderer::begin 中传入的主题统一决定。多种面材质的 sigma 不会各自触发独立模糊 pass。

自定义绘制

Canvas 提供 fill、stroke、line、ring、color_plane、text 和 glass。clip() 设置矩形裁剪；push_clip(rect, radius) / pop_clip() 支持最多 32 层形状裁剪，必须配对。backdrop() 将之前已绘制的内容重新冻结为随后玻璃的背景，避免玻璃采样到旧的画面。

单帧最多 65,536 条绘制指令。文本为系统字体灰度图集，字体缓存最多 16 张 2048² 纹理、24,000 个字形键；大量动态字号变化触及上限时会抛异常。使用同一个渲染器和稳定字号可以复用图集。

宿主 OpenGL 集成

宿主已持有 Win32 OpenGL 3.3 上下文时，可不创建 Window，直接在 current 的上下文中构造 Renderer。render 的末尾两个参数接收目标 FBO ID 与颜色附件，默认窗口 FBO 0 / GL_BACK。

目标必须是单采样 FBO，多重采样须由宿主先 resolve。渲染器恢复程序、VAO、FBO、viewport、scissor、blend、纹理和采样器等被修改的 GL 状态。宿主负责提供符合约定的绘制尺寸和有效颜色附件。

read_pixels(w,h) 返回默认窗口 back buffer 的自上而下 RGBA，在 swap 前调用。save_png(path,pixels) 使用 WIC 保存 PNG；它不读取宿主 FBO，也不捕获桌面。

生命周期和异常

窗口与渲染器只能在构造线程使用，渲染器的创建、使用和销毁必须保持原上下文 current。同进程只能有一个活动渲染器，可销毁后重新创建。Canvas 中已绑定的文字渲染服务仅在对应 Renderer 存活时有效。

无效范围或 UTF-8 抛 invalid_argument；不配对的 begin/end、重复 ID、错误线程/context 抛 logic_error；容量超限抛 length_error；Win32、GL、字体或 PNG 错误抛 runtime_error。错误线程或错误上下文析构 Renderer/Window 会终止进程，以避免在其他线程/context 错误释放 GPU 对象。

本版没有 Java 的布局树、表格、树控件、弹窗框架、绘图图表或全部复杂控件。Ui 状态仍由立即模式调用顺序和显式 Rect 控制。