从环境搭建到完整 API 参考。XGE 的公开接口声明在 xge.h、xui.h 与 xui_document.h 三个头文件中——这份文档与它们一一对应。
本节带你在 Windows + MinGW-w64 环境下，从克隆仓库到渲染出第一帧。
gcc（MinGW-w64）与 windres 在 PATH 中lib/XGE_OK 继续运行；返回其他值将退出主循环。使用 XGE_RUN_MANUAL 可改为手动驱动帧循环。所有资源型对象都以 typedef struct x_xxx_t* x_xxx 形式暴露句柄。创建型 API 通过输出参数返回句柄并返回 int 错误码；部分对象支持 AddRef / Free 引用计数。
通过 xgeScenePush / xgeScenePop 管理场景生命周期，每个场景拥有 onEnter / onUpdate / onDraw / onEvent 回调，支持暂停与恢复。
XUI 不直接依赖 XGE，而是通过 xui_proxy_t 声明所需渲染能力（Surface / Shape / Font / Path 等能力位）。这使得 XUI 可以运行在任何实现了代理接口的后端之上。
每个控件携带 LAYOUT / STYLE / CACHE / RENDER / TREE 五维脏标记，配合 SELF / SUBTREE / TILED / DISPLAY_LIST 缓存策略，只在必要时重绘。
仓库根目录提供全套批处理 / Shell 脚本，覆盖 DLL、测试与全部示例：
| 脚本 | 产物 | 说明 |
|---|---|---|
| build_dll.bat [profile] | build/<profile>/xge.dll + xge.lib | 按档位构建动态库（含 XUI） |
| build_dbg_dll.bat | build/xgedbg.dll | Debug 版，暴露调试统计 API |
| build_test.bat | build/xge_test.exe | 引擎冒烟测试 |
| build_android_ndk.bat | Android so | NDK 交叉编译 |
| build_ios_sim_exe.sh | iOS 模拟器可执行 | macOS 环境 |
xge.c 仅 4 行，通过包含 src/xge_impl.c 实现 unity build——你也可以将 src/ 下的 .c 文件逐个加入自己的工程系统。同一份代码，七个档位按需产出。xge_config.h 定义引擎与 3D 模块开关，xui_config.h 定义 65 个控件及服务开关（开关值必须为数字 0 或 1）；控件间的真实依赖记录在 tools/features.json，冲突由编译器报错并列出缺少的开关：
| 档位 | 能力 | 输出 |
|---|---|---|
| default（省略参数） | 保留旧默认能力，3D 关闭 | build/ |
| core | 窗口、输入、资源和 GPU 底座 | build/core/ |
| 2d | 基础二维，关闭文本和高级绘图 | build/2d/ |
| 3d | 三维及底座，关闭二维、文本、音频和 XUI | build/3d/ |
| ui-min | 二维、文本、XUI 核心与 Panel/Label/Button/Image | build/ui-min/ |
| full-dev | 所有已实现功能，包含三维 | build/full-dev/ |
| ide | 保留原有 IDE 的 xrt 扩展配置 | build/ide/ |
XGE3D_ENABLE_MODEL / LIGHTING / SHADOW / IBL / ANIMATION / TERRAIN / ASYNC / FOG 单独关闭。异步依赖 MODEL，动画依赖 MODEL，阴影依赖 LIGHTING，IBL 依赖 LIGHTING；FOG 仅依赖 3D，可用于无光照配置。库和消费者必须使用相同配置，构建产物携带完整的 xge_build_config.h 强制对齐。Linux 侧 ./build_dll.sh <profile> 尚未实机验证。| 函数 | 说明 |
|---|---|
| xgeInit(desc) | 按描述创建窗口并初始化引擎 |
| xgeRun(proc, user) | 进入主循环，每帧调用 proc |
| xgeBegin / xgeEnd | 手动模式下的帧包围 |
| xgeClear(color) | 以 RGBA8 颜色清屏 |
| xgeScenePush / Pop | 场景栈管理 |
| xgeCameraSet(cam) | 设置正交 / 透视相机 |
| xgeInvalidateRect(r) | 脏矩形失效，配合按需渲染 |
| xgeFrameStatsGet() | 帧时间 / DrawCall / 批次统计 |
路径构建、绘制属性、几何查询与场景组合四大类，共 180+ 个函数。
| 函数 | 说明 |
|---|---|
| xgeShapeExCreate / Destroy | 路径对象生命周期 |
| xgeShapeExMoveTo / LineTo / CubicTo / QuadTo / ArcTo | 路径构建原语 |
| xgeShapeExAppendSvgPath(s) | 直接解析 SVG path data |
| xgeShapeExFillColor / FillLinearGradient / FillRadialGradient | 填充paint |
| xgeShapeExStrokeWidth / Cap / Join / Dash | 描边属性 |
| xgeShapeExTrimPath(begin, end) | 路径裁剪动画 |
| xgeShapeExMaskShapeSet / MaskSceneSet | Alpha / Luma 遮罩 |
| xgeShapeExContainsPoint / GetBounds / GetLength | 几何查询 |
| xgeShapeExSceneAdd / SceneDraw | 场景图组合与整体变换 |
| xgeShapeExSceneEffectGaussianBlur / DropShadow | 场景级滤镜特效 |
| 函数 | 说明 |
|---|---|
| xgeSvgLoad / LoadMemory | 从 URI 或内存加载 SVG 文档 |
| xgeSvgLoadCached(uri) | 带全局缓存的加载 |
| xgeSvgDraw(svg, dst, tol) | 绘制到目标矩形（自动 viewBox 适配） |
| xgeSvgPaintGetByName | 按 id/name 取得子节点并单独变换 |
| xgeSvgRasterize / TextureLoad | 离屏光栅化到像素或纹理 |
| xgeSvgSetPreserveAspectRatio | 纵横比策略（meet / slice） |
右手系、Y 向上、米与弧度、列主序矩阵；节点属于场景，零值即根父节点。105 个公开函数覆盖场景、模型、光照、动画、地形与异步加载：
| 函数 | 说明 |
|---|---|
| xge3dSceneCreate / SceneFree | 场景对象生命周期；销毁节点会级联销毁后代 |
| xge3dNodeCreate / SetParent / SetTransform / SetMatrix | 节点树构建；SetMatrix 保留导入变换（含切变） |
| xge3dCameraPerspective / Orthographic / LookAt | 相机投影与视图矩阵 |
| xge3dModelLoad / LoadMemory / Instantiate / InstanceNode | glTF 2.0 / GLB 加载与场景实例化 |
| xge3dMaterialDefault / MaterialCreate / NodeSetMaterial | PBR metallic-roughness 材质与贴图绑定 |
| xge3dLightDefault / NodeSetLight | 方向光 / 点光 / 聚光灯（lux 与坎德拉单位） |
| xge3dShadowDefault | 级联阴影设置（1-4 级联，一个太阳 + 两个聚光） |
| xge3dEnvironmentCreate / EnvironmentSetIBL | 立方图天空与静态 IBL（辐照度 / 预滤波 / BRDF） |
| xge3dClipFromModel / ClipLoad / AnimatorCreate / AnimatorSetLayer | 动画剪辑与双层混合、事件与根运动 |
| xge3dTerrainCreate / TerrainSample / TerrainRaycast | 分块高度场（U16/F32）、三角形级采样与射线 |
| xge3dFogDefault | 线性距离雾（曝光与 sRGB 转换前混合） |
| xge3dLoaderRequest / Pump / Take | 异步加载与 GPU 上传预算（字节/操作/时间三重上限） |
| xge3dCameraScreenRay / SceneRaycast / SceneQueryAabb | 拾取射线与场景查询 |
| xge3dRender | 一帧渲染（相机/目标/清屏/天空/曝光/阴影/IBL/雾） |
| 函数 | 说明 |
|---|---|
| xgeFontLoad / LoadMemory | 加载 TTF（stb_truetype 光栅化） |
| xgeFontLoadXRF / SaveXRF | 自研 XRF 位图字体格式 |
| xgeFontFamilyResolve | 按字重/斜体解析字体族 |
| xgeTextShape(desc, run) | 文本整形为字形序列 |
| xgeGlyphRunDraw / DrawDecorated | 绘制字形序列（含装饰线） |
| xgeGlyphRunHitTest | 像素到字符的命中测试 |
| 函数 | 说明 |
|---|---|
| xuiCreate / xuiSetProxy | 创建上下文并绑定渲染代理（xuiProxyXge 取 XGE 默认代理） |
| xuiWidgetCreate / Destroy | 控件树节点 |
| xuiWidgetSetEventCallback(w, proc, user) | 控件事件回调（捕获/目标/冒泡） |
| xuiDispatchEvent / DispatchPendingEvents | 事件派发；xuiPollEvent 轮询、xuiClearEvents 清队 |
| xuiWidgetAddStyleClass / SetInlineStyle | 样式类与内联样式属性（可继承/私有） |
| xuiWidgetSetLayoutType / SetDock / SetAlign | 布局类型与停靠/对齐约束 |
| xuiThemeDefault / xuiSetTheme | 全局主题：一套结构体驱动全部控件配色 |
XUI_EVENT_PHASE_CAPTURE → TARGET → BUBBLE，回调返回 XUI_EVENT_DISPATCH_STOP 可中断传播。统一文档控件以共享句柄（xuiDocumentRetain / Release）持有内容，编辑器控件挂载文档；Markdown 支持 Source / Visual / Live MD 三种投影视图，共享同一修订与撤销历史。声明在 xui_document.h（154 个 API）：
| 函数 | 说明 |
|---|---|
| xuiDocumentCreate / Retain / Release | 共享文档对象生命周期 |
| xuiDocumentBeginTransaction | 事务化编辑（原子提交/回滚） |
| xuiDocumentAcquireSnapshot | 获取不可变快照，遍历块/行内语法与源位置 |
| xuiDocumentGetRevision | 单调修订号，驱动撤销与协同 |
| xuiDocumentEditorCreate(ctx, &desc, &widget) | 文档编辑器控件（归一化光标/选区/IME） |
| xuiDocumentEditorExecute / InsertText | 编辑命令与文本插入 |
| xuiDocumentImageResourceLoadFileAsync | 异步图片资源加载 |
examples/xui_document 演示左栏富文本 + 中栏三模式 Markdown 编辑 + 右栏实时预览，支持 Ctrl+Z/Y、B/I 与 Ctrl+滚轮缩放；build\xui_document.exe --verify 可跑自动化渲染校验。每个控件都遵循 xui<Name>Create(ctx, &widget, &desc) 的创建模式——上下文、输出控件句柄、描述结构体三参数；父子关系由容器 API 单独建立。控件配备独立测试（test_xui/）与示例（examples/）。完整列表见 首页控件画廊 或 示例库。
重点控件的设计文档位于仓库 docs/ 目录，包括布局系统、样式系统、渲染代理与缓存策略等架构说明。
| 后端 | 图形 | 入口 |
|---|---|---|
| SOKOL | GLCORE / GLES3 / Metal / D3D11 | xgeInit 默认 |
| EGL | GLES 3.0 | xgeEGLInit + 离屏渲染 |
| MINIPROGRAM | WebGL2 | xgeMiniProgramInit + Bridge |
| CUSTOM | 自定义 | xgePlatformBackendSet |