外

声明外部 C 函数（C-FFI），供玄铁直接调用。

外 函 XT_InitWindow(w: 整, h: 整, title: 字): 空

你可以……

• 声明后像普通函数一样调用：

外 函 XT_GetFPS(): 整
设 帧率 = XT_GetFPS()

• 包一层中文名再对外开放——库的常见写法：

外 函 XT_InitWindow(w: 整, h: 整, title: 字): 空

公 函 初始化窗口(宽, 高, 标题) {
    XT_InitWindow(宽, 高, 标题)
}

注意

• 参数与返回类型必须逐一标注；签名若与 C 侧实现不符，问题要到链接或运行期才暴露。
• 符号必须真实存在于所链接的 C 库或 runtime 中，否则链接失败。
• 返回值必须符合玄铁值编码（issue #44）：只能是 ① 玄铁对象指针（xt_string_new 等，带 XTObject 头与 magic）② 标记整数 XT_FROM_INT(值) ③ 真/假/空小常量。不得返回裸 C 指针——它 LSB=0 且 >4096，玄铁侧 ARC 会按堆对象校验 magic，读到 C 结构体即误报「堆损坏或非法指针访问」并退出。
• 资源句柄要用"槽位池 + XT_FROM_INT(槽号+1)"，0 表示失败：句柄是资源编号，不是内存地址。渲染桥的纹理/字体/音效/音乐流四处都是这个约定，可作参考实现。

浮点参数的两种约定（小数 vs 原生小数)

外 函 的浮点注解有两条 ABI 通道，用错即崩：

• 小数（装箱约定，默认）：参数/返回都按玄铁对象传（XTFloat 指针）。给 xt_ 系桥函数（runtime/官方桥）用——它们出入都是玄铁装箱值。
• 原生小数（原生 double ABI)：参数脱壳传 raw double，返回读 XMM0 后自动装箱。libm/标准 C 库直通用这条——sin、cos、pow、sqrt、floor 等：

外 函 sin(x: 原生小数): 原生小数
外 函 pow(x: 原生小数, y: 原生小数): 原生小数
示(sin(1.0))        // 0.8415
示(pow(2.0, 10.0))  // 1024

反例：外 函 sin(x: 小数): 小数 调 libm——参数把装箱指针当 double 传、返回把 raw double 当对象指针用，运行即堆损坏（这是 issue #77 的历史坑，写注解时务必分清"对面是玄铁桥还是原生 C")。

相关

函 · 引