— 玄铁渲染库编程指南

对标库版本: v1.2.7

底层基于 raylib 6.0，专注桌面 2D 渲染。本文档提供完整 API 参考、使用教程和实战示例。

快速开始

xuantie

引 "../lib/渲染/渲染.xt" 予 R

R.初始化窗口(800, 600, "我的应用")

当 非 R.窗口应关闭?() {
    R.开始绘图()
    R.清背景(30, 30, 50, 255)
    R.绘文字("Hello 玄铁", 100, 100, 20, 255, 255, 255, 255)
    R.结束绘图()
}

R.关闭窗口()

初始化窗口 默认开启 MSAA 4x 多重采样抗锯齿:圆角矩形、斜线、旋转纹理的边缘平滑无台阶;GPU 不支持时自动降级,无需任何配置。

编译方式（Go 种子或自举编译器均支持渲染链接）：

bash

# Go 种子
.\xt_gsc.exe tie .\程序.xt

# 自举编译器
.\xtc.exe tie .\程序.xt

窗口管理

创建与关闭

API	说明
`R.初始化窗口(宽, 高, "标题")`	创建窗口，自动设置 60 FPS 目标帧率
`R.窗口应关闭?()`	返回 `布尔`，用户点击关闭按钮或按 ESC 时为真
`R.关闭窗口()`	关闭窗口并释放 OpenGL 上下文
`R.窗口就绪?()`	窗口初始化完成返回真

属性控制

API	说明
`R.设置目标帧率(fps)`	调整帧率上限（如 30、60、120）
`R.取帧率()`	返回当前实际 FPS（整）
`R.取帧时间()`	返回上帧耗时秒（小数，double）
`R.取屏幕宽()`	当前屏幕宽度（整）
`R.取屏幕高()`	当前屏幕高度（整）
`R.设置窗口标题("新标题")`	运行时修改窗口标题，支持 Unicode（中文/日文等）

窗口模式（运行时可随时切换）

API	说明
`R.设窗口可调整(真/假)`	窗口边缘与角可否拖拽拉伸；默认固定大小
`R.设窗口无边框(真/假)`	去掉/恢复标题栏与边框。无边框后没有系统拖动区和关闭按钮，需自行实现（或保留 ESC 退出）
`R.设窗口全屏(真/假)`	进入/退出全屏；显式语义——目标状态与当前一致时调用无效果，不会来回翻转
`R.窗口全屏?()`	当前是否处于全屏（布尔）
`R.设窗口尺寸(宽, 高)`	运行时设置窗口尺寸
`R.设ESC关闭(真/假)`	按 ESC 是否请求关窗（默认真）；游戏等场景可关掉防止误触退出

开启可调整后，界面要跟随新尺寸需每帧取最新宽高布局：手动循环里用 R.取屏幕宽()/R.取屏幕高() 传给 UI.刷新(...) 即可（见 12 章 UI 指南）。

绘图帧控制

每帧必须成对调用 开始绘图 和 结束绘图，所有绘制指令在二者之间。

API	说明
`R.开始绘图()`	开始一帧，准备画布
`R.结束绘图()`	结束一帧，交换前后缓冲区
`R.清背景(r, g, b, a)`	用纯色填充背景，各通道 0–255

形状绘制

全部使用 RGBA 颜色（每个通道 0–255 整数）。

API	参数
`R.绘像素(x, y, r, g, b, a)`	单点
`R.绘直线(x1, y1, x2, y2, r, g, b, a)`	线段
`R.绘矩形(x, y, 宽, 高, r, g, b, a)`	实心矩形
`R.绘矩形线(x, y, 宽, 高, r, g, b, a)`	矩形边框
`R.绘圆(cx, cy, 半径, r, g, b, a)`	实心圆
`R.绘圆线(cx, cy, 半径, r, g, b, a)`	圆形边框
`R.绘椭圆(cx, cy, 水平半径, 垂直半径, r, g, b, a)`	实心椭圆
`R.绘三角(x1, y1, x2, y2, x3, y3, r, g, b, a)`	实心三角形
`R.绘多边形(cx, cy, 边数, 半径, 旋转角, r, g, b, a)`	正多边形

文字渲染

默认字体（仅 ASCII）

API	说明
`R.绘文字("文本", x, y, 字号, r, g, b, a)`	用 raylib 内置位图字体渲染（仅 ASCII 32–126）
`R.量文字("文本", 字号)`	测量文本像素宽度（整）
`R.绘帧率(x, y)`	在指定位置显示 FPS 计数器

自定义字体

支持格式：.ttf / .otf / .ttc（字体集合，取容器内第 1 个 face，加载失败返回 0 并回退 raylib 默认字体）。注意：苹方/冬青黑体等 CFF 格式字体 stb 无法解码，加载系统字体 命中时会自动兜底黑体。

加载模式

API	纹理大小	适用场景
`R.加载系统字体("微软雅黑", 字号)`	按需（图集缓存）	推荐。按系统字体名取字体，不必自己带文件；Windows 走 GDI 光栅化（灰阶抗锯齿、生僻字系统回落、按需栅格化），macOS/Linux 映射到系统自带字体文件后经 raylib 载入
`R.加载字体("路径.ttf", 字号)`	~8192×4096（全 CJK）	需要自带字体文件/跨机器字形一致的场景。注意：字号 ≥28px 保证可读清晰度
`R.加载字体精准("路径.ttf", 字号, "参考文本")`	~256×256	已知渲染内容，追求极致清晰轻量

系统字体模式：用系统字体名直接取字体，无需字体文件路径。

Windows：GDI GetGlyphOutlineW 光栅化，视觉效果与记事本等系统应用同级；只栅格化实际用到的字符并缓存进动态图集，多字号各自独立缓存。字体名如 "微软雅黑"/"宋体"/"Consolas"。
macOS：无 GDI，改为把系统字体名映射到自带字体文件后经 raylib 载入（苹方/PingFang、黑体/Heiti、冬青黑体/Hiragino、宋体/Songti、楷体/Kaiti）。名字里带 / 或字体扩展名时按路径直用，所以 R.加载系统字体("/某处/字体.ttc", 28) 也成立。
Linux：同样支持传路径；内置常见路径候选（文泉驿、Noto CJK）。
名字未命中或字体文件不存在时回退系统 CJK 默认字体（与 Windows 的字体回落同义）；一个都取不到才返回 0（绘制回退 raylib 默认字体）。返回句柄与 绘字体文字/量字体文字/释字体 完全通用。

中文要显示出来，必须先加载字体：绘文字() 走 raylib 内置位图字体，只有 ASCII（32–126），中文会显示为方块。渲染层不随包带字体（UI 库自带鸿蒙字体是 UI 层的事），所以要中文就 加载系统字体 或 加载字体(路径, 字号)。

全范围模式内部加载 ASCII(32–126) + CJK 统一汉字基本区(U+4E00–U+9FFF, ~21K 码点)。纹理 ~32 MB。

精准模式从参考文本中自动解码 UTF-8 提取所有非 ASCII 码点（去重），仅加载 ASCII + 这些码点。纹理 ~128 KB，100% 不缺字。

建议：中文界面优先用系统字体模式（免字体文件、系统级观感）；需要自带字体或跨机器字形一致时用全范围/精准模式。

使用

API	说明
`R.绘字体文字(句柄, "文本", x, y, 字号, 间距, r, g, b, a)`	用指定字体渲染（间距通常 1–2）
`R.量字体文字(句柄, "文本", 字号, 间距)`	用指定字体精确测量文字宽度（布局尺寸/居中对齐用）
`R.释字体(句柄)`	释放字体 GPU 资源

完整示例：

xuantie

设 显示文本 = "玄铁3D球体旋转"

// 精准模式：参考文本确保所有目标字符被加载
设 字体 = R.加载字体精准(
    "assets/HarmonyOS_Sans_SC_Regular.ttf",
    28,
    显示文本 & "Lambertian 光照 FPS0123456789|"
)
设 字体小 = R.加载字体精准(
    "assets/HarmonyOS_Sans_SC_Regular.ttf",
    18,
    显示文本 & "Lambertian 光照 FPS0123456789|"
)

当 非 R.窗口应关闭?() {
    R.开始绘图()
    R.清背景(15, 15, 35, 255)
    R.绘字体文字(字体, 显示文本, 20, 20, 28, 2, 255, 255, 255, 255)
    R.绘字体文字(字体小, "Lambertian 光照 | 60 FPS", 20, 54, 18, 1, 200, 200, 220, 255)
    R.绘帧率(700, 20)
    R.结束绘图()
}

R.释字体(字体)
R.释字体(字体小)

纹理与图像

加载 PNG 等格式到 GPU 纹理，可高效绘制。

API	说明
`R.加载纹理("路径.png")`	从文件加载纹理(png/bmp/gif,支持中文路径),返回整型句柄(0 = 失败)
`R.释纹理(句柄)`	释放 GPU 纹理资源
`R.绘纹理(句柄, x, y, tr, tg, tb, ta)`	原尺寸绘制（t 参数为着色，255/255/255/255 = 无着色）
`R.绘纹理Ex(句柄, x, y, 旋转角, 缩放, tr, tg, tb, ta)`	带旋转（度）和缩放倍率的绘制
`R.量纹理宽(句柄)` / `R.量纹理高(句柄)`	查询纹理像素宽/高
`R.绘纹理区(句柄, x, y, 宽, 高, tr, tg, tb, ta)`	整图缩放到指定宽×高矩形绘制(UI 图标适配栏高用)
`R.加载SVG纹理("路径.svg", 宽, 高)`	SVG 经内置 nanosvg 光栅化为纹理;宽/高传 0 取 SVG 固有尺寸,否则等比缩放进宽×高

资源句柄与支持的图片格式

句柄是"槽位编号"(标记整数),0 表示失败:文件缺失、解码失败、槽位耗尽都返回 0,用 != 0 即可判成败。纹理解码失败不会再返回"非 0 但尺寸为 0"的空纹理。
支持的图片格式:png / bmp / gif 可用;jpg 与 tga 当前不可用——实测不同来源的基线 JPEG、灰度 JPEG 一律报 IMAGE: Data format not supported,TGA 同样失败;需要这些格式请先转 PNG。根因是随包 raylib 静态库未编译 JPG/TGA 解码器(见 issue #44)。

千分定点绘制(亚像素)

绘矩形精/绘矩形线精/绘圆角矩形精/绘圆角矩形线精/绘纹理区精/绘字体文字精 —— 参数与对应普通版相同,仅坐标/尺寸改传 ×1000 定点整数(绘字体文字精 另多一个"缩放千"参数,1000 = 原倍):

桥内转 float 由 GPU 亚像素渲染:微交互/动画的小行程移动逐帧平滑,无整数像素台阶
文字坐标仍建议像素对齐(半像素位置会被重采样成虚边);框体几何无需对齐
文字缩放走字形图集 GPU 拉伸(双线性),不换字号重光栅化,字形不变形

圆角渐变纹理生成器

R.生成渐变纹理(宽, 高, r1,g1,b1,a1, r2,g2,b2,a2, 方向, 圆角, 羽化) —— 逐像素生成双色线性渐变纹理:

方向:0 = 横向,1 = 竖向
圆角:像素圆角(0 = 直角);边缘由 SDF 覆盖度计算,天然抗锯齿
羽化:边缘过渡像素数(1 = 仅抗锯齿;>1 产生向外柔边)
两色取同一色即"圆角羽化纯色块"
桥内带 8 槽参数缓存:每帧同参调用直接命中,不重复生成;缓存满轮转淘汰

UI 库的 底色2/渐变向/羽化 选项即由它驱动。纹理句柄与 绘纹理区 等绘制 API 通用,但不要对缓存句柄调 释纹理(缓存轮转时由桥自动释放)。

键盘与鼠标输入

键盘

API	说明
`R.键按下?(键码)`	按键持续按下
`R.键刚按下?(键码)`	按键本帧刚按下（边沿触发，不会重复触发）
`R.取按键()`	返回最后按下的键码（整），无按键返回 0

键码常量：

常量	对应按键
`R.键右` `R.键左` `R.键下` `R.键上`	方向键
`R.键空格` `R.键ESC` `R.键回车` `R.键退格`	常用键
`R.键A`–`R.键F`、`R.键W` `R.键S` `R.键D` `R.键R`	字母（其余需用键码整数值）
`R.键左Shift` `R.键右Shift` `R.键左Ctrl` `R.键右Ctrl` `R.键左Alt` `R.键右Alt` `R.键左命令` `R.键右命令`	修饰键（`键Ctrl` 为左 Ctrl；命令键即 macOS 的 ⌘）。键码以 `lib/渲染/raylib.h` 为准，勿按第三方头文件猜测

鼠标

API	说明
`R.鼠标按下?(按钮)`	鼠标按钮持续按下
`R.鼠标刚按下?(按钮)`	鼠标按钮本帧刚按下
`R.鼠X()`	当前鼠标 X 坐标（整）
`R.鼠Y()`	当前鼠标 Y 坐标（整）
`R.取鼠标滚轮()`	滚轮增量（整，正=向上，负=向下）

鼠标常量：R.鼠左键 R.鼠右键 R.鼠中键

音频

句柄规则同纹理:加载音效/加载音乐流 失败(文件缺失、解码失败、槽位耗尽)一律返回 0,用 != 0 判断成败。句柄是槽位编号(标记整数)——不要当指针用,也不要拿 -1 之类哨兵值去比。早期的裸指针句柄会让 ARC 误判"堆损坏"并直接退出(see issue #44),现已统一。

音频设备

API	说明
`R.初始化音频()`	初始化音频设备（使用任何音频 API 前调用）
`R.关闭音频()`	关闭音频设备

短音效

整段加载到内存，适合短促音效（< 5 秒）。

API	说明
`R.加载音效("路径.wav")`	加载 WAV，返回整型句柄
`R.播音效(句柄)`	播放一次
`R.释音效(句柄)`	释放内存

长音乐流

流式解码，适合背景音乐。

API	说明
`R.加载音乐流("路径.mp3")`	打开流，返回整型句柄
`R.播音乐流(句柄)`	开始播放
`R.更新音乐流(句柄)`	每帧调用一次，解码下一段数据
`R.停音乐流(句柄)`	停止播放
`R.释音乐流(句柄)`	关闭流并释放

工具函数

API	说明
`R.取随机数(最小值, 最大值)`	返回 [min, max] 内随机整数
`R.取运行时间()`	程序启动至今的秒数（小数，double）
`R.暂停(秒数)`	暂停指定秒数（小数，double）（注：语言关键字是 `等待`，故封装名用 `暂停`)
`R.截图("文件名.png")`	当前帧缓冲导出 PNG。必须在一帧 `R.结束绘图()` 之后调用（截的是已呈现的帧；结束绘图之前调用会拿到未完成的背景缓冲）。相对路径按当前工作目录解析,也可写绝对路径

颜色常量

未提供 RGBA 参数时可直接使用：

R.白 R.黑 R.红 R.绿 R.蓝 R.黄 R.青 R.紫 R.橙 R.灰 R.深灰 R.浅灰 R.透明

故障排查

现象	原因	解决
中文显示 `???`	码点不在加载范围内	用 `加载字体精准` 并在参考文本中包含所有目标字符
字体加载但全部 `???`	字体不含所需字形，或为 CFF 格式（如苹方）	换含中文的 `.ttf`；系统字体用 `加载系统字体`（CFF 自动兜底黑体）
字体模糊	全范围模式下字号太小	字号提升到 28px 以上，或切换到精准模式
`invalid redefinition`	自举编译器旧版本	更新到 v0.18.6+
链接 `XT_InitWindow` 未定义	自举编译器未启用渲染链接	确保 `render/渲染桥.c` 和 `libraylib.a` 存在
窗口关闭按钮无效	自举编译器旧版本	更新到 v0.18.6+

— 玄铁渲染库编程指南 ​

快速开始 ​

窗口管理 ​

创建与关闭 ​

属性控制 ​

窗口模式（运行时可随时切换） ​

绘图帧控制 ​

形状绘制 ​

文字渲染 ​

默认字体（仅 ASCII） ​

自定义字体 ​

加载模式 ​

使用 ​

纹理与图像 ​

资源句柄与支持的图片格式 ​

千分定点绘制(亚像素) ​

圆角渐变纹理生成器 ​

键盘与鼠标输入 ​

键盘 ​

鼠标 ​

音频 ​

音频设备 ​

短音效 ​

长音乐流 ​

工具函数 ​

颜色常量 ​

故障排查 ​