渲染库是什么

玄铁渲染库是官方桌面 2D 渲染库，基于 raylib 桥接（渲染桥 渲染桥.c 封装平台窗口系统），函数以 R. 前缀调用。raylib 本身是跨平台库（Windows /macOS/ Linux 均支持），玄铁渲染库在其上提供中文 API。Windows 侧渲染桥走 Win32 / GDI，macOS / Linux 侧走 raylib 原生 API。

快速上手

引 "渲染" 予 R

设 窗口宽 = 800
设 窗口高 = 600

R.初始化窗口(窗口宽, 窗口高, "示例窗口")
R.设ESC关闭(真)

当 非 R.窗口应关闭?() {
    R.开始绘图()
    R.清背景(...)
    R.结束绘图()
}

R.关闭窗口()

窗口与绘图 API

函数	说明
R.初始化窗口(宽, 高, 标题)	创建窗口（必须在其他渲染调用前执行）
R.设ESC关闭(真)	按 ESC 是否退出主循环
R.窗口应关闭?()	主循环退出条件判断
R.开始绘图() / R.结束绘图()	一帧绘制的开始 / 结束
R.清背景(颜色)	清屏填充背景
R.截图(路径)	保存当前画面为图片
R.关闭窗口()	关闭窗口并释放资源

字体系统

玄铁渲染库的字体加载分三条路径：

加载方式	用法	说明
默认字体	直接用 R.绘文字(文本, 位置, 字号, 颜色)	raylib 内置位图字体，仅拉丁字符，无中文
加载系统字体	R.加载系统字体(字体名, 字号)	Windows 走系统字体直取；macOS 已适配 Apple TTC 字体容器，宋体 / 楷体等中文渲染正常
加载字体文件	R.加载字体(路径, 字号)	直接加载 ttf /ttc 字体文件，支持中文
加载字体精准	R.加载字体精准(路径, 字号, 参考文本)	按参考文本裁剪字形，加载更精确

实测要点：

• 中文显示依赖字体文件或系统字体通道；默认字体不含中文字形（画中文显示方块）。

• macOS 侧加载系统字体（如「宋体」「楷体」）已修复：Apple TTC 字体容器重组、伪成功消除，中文渲染正常。

• 字体加载必须在 R.初始化窗口 之后（GPU 上下文就绪），开窗前加载中文画不出来。

• 字体池有上限（实测为 8 个句柄），超限返回空句柄。

图片纹理

格式	支持状态（macOS 实测）
PNG	支持
BMP	支持
GIF	支持
JPG	不支持（解码缺失，需转 PNG）
TGA	不支持

纹理操作：R.加载纹理(路径)、R.量纹理宽/高(句柄) 判断加载成败；解码失败时句柄语义需按「纹理尺寸为 0」判断（已知问题，上游处理中）。

音效与音乐

R.加载音效(路径)、R.加载音乐流(路径) 加载音频资源（wav 等），返回句柄播放 / 停止 / 释放。音频句柄按槽位池管理（与纹理、字体一致），不返回裸指针。

平台适配现状

平台	状态
Windows	主力平台，完整支持（Win32 / GDI）
macOS arm64	已适配：渲染桥平台分支、字体 TTC 中文通道、关窗语义对齐
Linux	走 raylib 原生路径，随跨平台适配同步

已知问题：渲染库链接在 macOS 需手动指定 raylib 与系统框架（Cocoa / OpenGL / IOKit / CoreVideo）；工具链侧有抓取中间产物 + 手动链接的绕行方案。

声明式 UI 库

玄铁在渲染库上层提供声明式 UI 库（桌面组件：按钮、布局等）。已知事实：UI 默认主题支持按钮三态（普通 / 悬浮 / 按下）、圆角 8px，内置鸿蒙字体实现零配置中文显示。UI 层 API 细节请查阅官方文档（仓库 GUIDE/ 目录的渲染库与 UI 编程指南），本篇未展开。

参考

• 官方 GitHub 仓库：https://github.com/MARKJY-China/XuanTie-Lang

• 渲染库仓库：https://atomgit.com/MARKJY/XuanTieRendering

• 官方文档：仓库 GUIDE/ 目录（09_渲染库编程指南）