xbintsc 0.5.45 → 0.5.51

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. package/AGENTS.md +1 -1
  2. package/README.md +5 -4
  3. package/README.zh-CN.md +4 -3
  4. package/dist/src/cli/extensions.d.ts +24 -0
  5. package/dist/src/cli/extensions.js +62 -0
  6. package/dist/src/cli/extensions.js.map +1 -0
  7. package/dist/src/cli/help.d.ts +1 -1
  8. package/dist/src/cli/help.js +3 -1
  9. package/dist/src/cli/help.js.map +1 -1
  10. package/dist/src/cli/hints.js +8 -3
  11. package/dist/src/cli/hints.js.map +1 -1
  12. package/dist/src/cli/main.js +21 -28
  13. package/dist/src/cli/main.js.map +1 -1
  14. package/dist/src/diagnostics/diagnostic.d.ts +3 -1
  15. package/dist/src/diagnostics/diagnostic.js +2 -0
  16. package/dist/src/diagnostics/diagnostic.js.map +1 -1
  17. package/dist/src/driver/build-key.d.ts +2 -0
  18. package/dist/src/driver/build-key.js +1 -0
  19. package/dist/src/driver/build-key.js.map +1 -1
  20. package/dist/src/driver/compiler.js +61 -8
  21. package/dist/src/driver/compiler.js.map +1 -1
  22. package/dist/src/driver/config.d.ts +4 -0
  23. package/dist/src/driver/config.js +2 -0
  24. package/dist/src/driver/config.js.map +1 -1
  25. package/dist/src/driver/link-features.d.ts +37 -0
  26. package/dist/src/driver/link-features.js +123 -0
  27. package/dist/src/driver/link-features.js.map +1 -0
  28. package/dist/src/driver/options.d.ts +10 -0
  29. package/dist/src/driver/runtime-objects.d.ts +5 -0
  30. package/dist/src/driver/runtime-objects.js +20 -1
  31. package/dist/src/driver/runtime-objects.js.map +1 -1
  32. package/dist/src/driver/usage.d.ts +23 -0
  33. package/dist/src/driver/usage.js +353 -0
  34. package/dist/src/driver/usage.js.map +1 -0
  35. package/dist/src/driver/version.d.ts +1 -1
  36. package/dist/src/driver/version.js +1 -1
  37. package/dist/src/extensions/catalog.js +1 -2
  38. package/dist/src/extensions/catalog.js.map +1 -1
  39. package/dist/src/extensions/gui/features.d.ts +31 -0
  40. package/dist/src/extensions/gui/features.js +160 -0
  41. package/dist/src/extensions/gui/features.js.map +1 -0
  42. package/dist/src/extensions/gui/index.js +10 -4
  43. package/dist/src/extensions/gui/index.js.map +1 -1
  44. package/dist/src/extensions/link-feature.d.ts +70 -0
  45. package/dist/src/extensions/link-feature.js +18 -0
  46. package/dist/src/extensions/link-feature.js.map +1 -0
  47. package/dist/src/extensions/registry.d.ts +24 -4
  48. package/dist/src/extensions/registry.js +26 -3
  49. package/dist/src/extensions/registry.js.map +1 -1
  50. package/dist/src/index.d.ts +3 -2
  51. package/dist/src/index.js +0 -1
  52. package/dist/src/index.js.map +1 -1
  53. package/dist/tests/cli/hints.test.js +5 -7
  54. package/dist/tests/cli/hints.test.js.map +1 -1
  55. package/dist/tests/driver/link-features.test.js +105 -0
  56. package/dist/tests/driver/link-features.test.js.map +1 -0
  57. package/dist/tests/driver/usage.test.d.ts +1 -0
  58. package/dist/tests/driver/usage.test.js +88 -0
  59. package/dist/tests/driver/usage.test.js.map +1 -0
  60. package/dist/tests/e2e/gui-audio.test.js +4 -4
  61. package/dist/tests/e2e/gui-audio.test.js.map +1 -1
  62. package/dist/tests/e2e/gui-feature-linking.test.d.ts +9 -0
  63. package/dist/tests/e2e/gui-feature-linking.test.js +68 -0
  64. package/dist/tests/e2e/gui-feature-linking.test.js.map +1 -0
  65. package/dist/tests/e2e/gui-helpers.d.ts +5 -1
  66. package/dist/tests/e2e/gui-helpers.js +2 -0
  67. package/dist/tests/e2e/gui-helpers.js.map +1 -1
  68. package/dist/tests/e2e/gui-layout.test.js +4 -1
  69. package/dist/tests/e2e/gui-layout.test.js.map +1 -1
  70. package/dist/tests/e2e/gui-media-disabled.test.d.ts +5 -4
  71. package/dist/tests/e2e/gui-media-disabled.test.js +7 -6
  72. package/dist/tests/e2e/gui-media-disabled.test.js.map +1 -1
  73. package/dist/tests/e2e/gui-media.test.d.ts +5 -4
  74. package/dist/tests/e2e/gui-media.test.js +9 -9
  75. package/dist/tests/e2e/gui-media.test.js.map +1 -1
  76. package/dist/tests/e2e/gui-paint.test.js +5 -2
  77. package/dist/tests/e2e/gui-paint.test.js.map +1 -1
  78. package/dist/tests/e2e/gui-shaping.test.d.ts +5 -0
  79. package/dist/tests/e2e/gui-shaping.test.js +47 -0
  80. package/dist/tests/e2e/gui-shaping.test.js.map +1 -0
  81. package/dist/tests/e2e/gui-webgl-pipeline-cache.test.d.ts +18 -0
  82. package/dist/tests/e2e/gui-webgl-pipeline-cache.test.js +120 -0
  83. package/dist/tests/e2e/gui-webgl-pipeline-cache.test.js.map +1 -0
  84. package/dist/tests/extensions/gui-features.test.d.ts +1 -0
  85. package/dist/tests/extensions/gui-features.test.js +168 -0
  86. package/dist/tests/extensions/gui-features.test.js.map +1 -0
  87. package/doc/ai/cli.md +5 -1
  88. package/doc/ai/extensions.md +48 -23
  89. package/doc/ai/troubleshooting.md +10 -7
  90. package/doc/ai/zh-CN/cli.md +5 -1
  91. package/doc/ai/zh-CN/extensions.md +41 -20
  92. package/doc/ai/zh-CN/troubleshooting.md +6 -5
  93. package/doc/gui/api.md +2 -1
  94. package/doc/gui/build.md +136 -19
  95. package/doc/gui/canvas.md +1 -1
  96. package/doc/gui/known-issues.md +32 -3
  97. package/doc/gui/layout.md +1 -1
  98. package/doc/gui/media.md +13 -7
  99. package/doc/gui/rendering.md +32 -15
  100. package/doc/gui/runtime.md +5 -0
  101. package/doc/gui/webgl.md +24 -6
  102. package/doc/gui.md +50 -35
  103. package/doc/implemented/cli.md +2 -0
  104. package/doc/implemented/extensions.md +9 -3
  105. package/doc/npm-package.md +4 -4
  106. package/doc/xbintsc.config.schema.json +10 -0
  107. package/doc/zh-CN/gui/api.md +2 -1
  108. package/doc/zh-CN/gui/build.md +110 -16
  109. package/doc/zh-CN/gui/canvas.md +1 -1
  110. package/doc/zh-CN/gui/known-issues.md +24 -3
  111. package/doc/zh-CN/gui/layout.md +1 -1
  112. package/doc/zh-CN/gui/media.md +11 -6
  113. package/doc/zh-CN/gui/rendering.md +26 -9
  114. package/doc/zh-CN/gui/runtime.md +3 -0
  115. package/doc/zh-CN/gui/webgl.md +3 -3
  116. package/doc/zh-CN/gui.md +42 -29
  117. package/doc/zh-CN/implemented/cli.md +2 -0
  118. package/doc/zh-CN/implemented/extensions.md +9 -3
  119. package/doc/zh-CN/npm-package.md +4 -3
  120. package/package.json +7 -7
  121. package/runtime/ext_gui/browser.cpp +22 -15
  122. package/runtime/ext_gui/browser_loop.cpp +13 -1
  123. package/runtime/ext_gui/canvas.h +1 -1
  124. package/runtime/ext_gui/canvas_raster.cpp +1 -1
  125. package/runtime/ext_gui/canvas_text.cpp +1 -1
  126. package/runtime/ext_gui/dom_api_canvas.cpp +15 -8
  127. package/runtime/ext_gui/dom_api_canvas_extra.cpp +44 -20
  128. package/runtime/ext_gui/dom_api_canvas_image.cpp +3 -1
  129. package/runtime/ext_gui/dom_api_node_read.cpp +10 -0
  130. package/runtime/ext_gui/dom_api_offscreen.cpp +3 -1
  131. package/runtime/ext_gui/dom_api_style.cpp +7 -0
  132. package/runtime/ext_gui/dom_api_webgl_internal.h +4 -0
  133. package/runtime/ext_gui/dom_api_webgl_source.cpp +5 -2
  134. package/runtime/ext_gui/gpu_bridge.c +28 -0
  135. package/runtime/ext_gui/gpu_feature.cpp +30 -0
  136. package/runtime/ext_gui/gpu_shader.cpp +22 -0
  137. package/runtime/ext_gui/gpu_shader_api.h +50 -0
  138. package/runtime/ext_gui/gui.cpp +6 -37
  139. package/runtime/ext_gui/gui_canvas.cpp +14 -6
  140. package/runtime/ext_gui/gui_engine.h +1 -18
  141. package/runtime/ext_gui/gui_events.cpp +3 -2
  142. package/runtime/ext_gui/gui_webgl.cpp +25 -10
  143. package/runtime/ext_gui/image_api.cpp +18 -0
  144. package/runtime/ext_gui/image_api.h +41 -0
  145. package/runtime/ext_gui/image_bitmap_browser.cpp +20 -11
  146. package/runtime/ext_gui/image_bridge.c +22 -0
  147. package/runtime/ext_gui/image_feature.cpp +105 -0
  148. package/runtime/ext_gui/layout.cpp +13 -8
  149. package/runtime/ext_gui/layout.h +2 -2
  150. package/runtime/ext_gui/media.cpp +4 -2
  151. package/runtime/ext_gui/media.h +3 -3
  152. package/runtime/ext_gui/media_api.h +7 -6
  153. package/runtime/ext_gui/renderer.h +1 -1
  154. package/runtime/ext_gui/renderer_image.cpp +13 -6
  155. package/runtime/ext_gui/renderer_layer.cpp +10 -5
  156. package/runtime/ext_gui/stb_truetype.h +5077 -0
  157. package/runtime/ext_gui/text.cpp +24 -498
  158. package/runtime/ext_gui/text.h +7 -5
  159. package/runtime/ext_gui/text_api.h +45 -0
  160. package/runtime/ext_gui/text_bridge.c +23 -0
  161. package/runtime/ext_gui/text_cache.cpp +1 -1
  162. package/runtime/ext_gui/text_glyph_cache.cpp +2 -2
  163. package/runtime/ext_gui/text_hb.cpp +554 -0
  164. package/runtime/ext_gui/text_stb.cpp +513 -0
  165. package/runtime/ext_gui/webgl_api.cpp +19 -0
  166. package/runtime/ext_gui/webgl_api.h +53 -0
  167. package/runtime/ext_gui/webgl_bridge.c +25 -0
  168. package/runtime/ext_gui/webgl_draw_setup.cpp +42 -1
  169. package/runtime/ext_gui/webgl_feature.cpp +82 -0
  170. package/runtime/ext_gui/webgl_feature.h +28 -0
  171. package/runtime/ext_gui/webgl_msl.cpp +41 -0
  172. package/runtime/ext_gui/webgl_msl.h +6 -0
  173. package/runtime/ext_gui/webgl_shader.cpp +40 -32
  174. package/runtime/ext_gui/window.cpp +7 -7
  175. package/runtime/ext_media/decode_audio.cpp +1 -1
  176. package/runtime/ext_media/media.cpp +1 -1
  177. package/runtime/ext_media/media_bridge.c +7 -7
  178. package/scripts/build-gui.ts +97 -98
  179. package/scripts/check-file-length.ts +1 -0
  180. package/scripts/gui-build-options.ts +122 -0
  181. package/src/cli/extensions.ts +72 -0
  182. package/src/cli/help.ts +3 -1
  183. package/src/cli/hints.ts +9 -3
  184. package/src/cli/main.ts +21 -27
  185. package/src/diagnostics/diagnostic.ts +2 -0
  186. package/src/driver/build-key.ts +3 -0
  187. package/src/driver/compiler.ts +63 -8
  188. package/src/driver/config.ts +6 -0
  189. package/src/driver/link-features.ts +163 -0
  190. package/src/driver/options.ts +10 -0
  191. package/src/driver/runtime-objects.ts +26 -1
  192. package/src/driver/usage.ts +376 -0
  193. package/src/driver/version.ts +1 -1
  194. package/src/extensions/catalog.ts +1 -2
  195. package/src/extensions/gui/features.ts +162 -0
  196. package/src/extensions/gui/index.ts +10 -4
  197. package/src/extensions/link-feature.ts +72 -0
  198. package/src/extensions/registry.ts +45 -4
  199. package/src/index.ts +3 -2
  200. package/dist/src/extensions/media/index.d.ts +0 -28
  201. package/dist/src/extensions/media/index.js +0 -59
  202. package/dist/src/extensions/media/index.js.map +0 -1
  203. package/dist/tests/extensions/media.test.js +0 -63
  204. package/dist/tests/extensions/media.test.js.map +0 -1
  205. package/src/extensions/media/index.ts +0 -65
  206. /package/dist/tests/{extensions/media.test.d.ts → driver/link-features.test.d.ts} +0 -0
@@ -124,25 +124,29 @@ shader 合成到场景上。全部十六种 CSS 模式(`multiply`、`screen`
124
124
 
125
125
  ## 文本技术栈(M4b)
126
126
 
127
- `runtime/ext_gui/text.{h,cpp}` 封装 **HarfBuzz**(整形)与 **FreeType**(度量
128
- 与最终光栅化)。两者都静态构建,并由 `scripts/build-gui.ts` 链接进 `gui.a`。
127
+ `runtime/ext_gui/text.{h,cpp}` 是前端,通过一个小型后端表分发。默认后端是内置的
128
+ **stb_truetype**(`text_stb.cpp`、`runtime/ext_gui/stb_truetype.h`)。可选的
129
+ **`shaping`** 链接特性会安装 `text_hb.cpp`(HarfBuzz + FreeType 后端),非 ASCII
130
+ 文本会自动选中它。
129
131
 
130
132
  - 字体从常见系统路径解析(macOS 上的 Helvetica/Arial、Linux 上的
131
133
  DejaVu/Liberation、Windows 上的 Segoe UI/Arial),可用 `XT_GUI_FONT`
132
134
  (以及 `XT_GUI_FONT_MONO`)覆盖,并按 `(字体类别, 字号)` 缓存。目前只使用
133
135
  常规直立字面;字重/斜体选择是后续细化。
136
+ - 默认候选优先选择 **CJK 覆盖的 TrueType/TTC** 字面(Windows 的 Microsoft
137
+ YaHei、macOS 的 PingFang/STHeiti、Linux 的 Noto Sans CJK/WenQuanYi),
138
+ 再是纯拉丁字面。stb_truetype 无法解析的候选(例如 CFF/OTF 集合)会被跳过,
139
+ 继续尝试下一个。
134
140
  - **主字面缺少的码点会回退到其他字面。** 引擎维护一条小的回退链——先平台的
135
141
  符号字体(Segoe UI Symbol、Apple Symbols、Noto Sans Symbols、DejaVu Sans),
136
142
  再是另一字体类别——并为每个码点解析出回退链中第一个拥有该字形的字面。
137
143
  run 以每个字面一段的方式整形,因此混合 run(拉丁文加箭头、制表符或几何图形,
138
144
  或 CJK 中的拉丁文)会绘制每个字形,而不是把缺失的字形当作 `.notdef` 丢弃。
139
- 这正是让诸如 `▮`/`▯`(U+25AE/U+25AF,鹈鹕自行车速度条所用)这样的字符在
140
- CJK 主字面没有几何图形时仍能显示的原因。每个整形后的字形携带自己的字面
141
- (`ShapedGlyph::font`),渲染器据此从正确的图集条目光栅化;`xt_text_scale`
142
- 把字面映射到显示的缩放系数。
143
- - `xt_text_measure_width` 用 HarfBuzz 对 run 整形(因此字距调整与连字会生效),
144
- `xt_text_metrics` 返回 FreeType 的 ascent / descent / 正常行高。当找不到
145
- 字体文件时,模块回退到确定性的逐字节近似,因此布局仍可工作。
145
+ 每个整形后的字形携带自己的字面(`ShapedGlyph::font`),渲染器据此从正确的
146
+ 图集条目光栅化;`xt_text_scale` 把字面映射到显示的缩放系数。
147
+ - `xt_text_measure_width` 把每个码点映射为字形并累加 advance 与字体的 `kern`
148
+ 表;`xt_text_metrics` 返回 stb_truetype 的 ascent / descent / 正常行高。
149
+ 当找不到字体文件时,模块回退到确定性的逐字节近似,因此布局仍可工作。
146
150
  - `xt_text_shape_run` 返回定位后的字形,`xt_text_rasterize` 渲染 8 位位图;
147
151
  渲染器把它们打包进图集。在 HiDPI 显示器上,字形以
148
152
  `font_size * SDL_GetWindowPixelDensity` 光栅化,而四边形以逻辑像素定位,
@@ -150,6 +154,13 @@ shader 合成到场景上。全部十六种 CSS 模式(`multiply`、`screen`
150
154
  - 布局使用这些真实度量进行文本宽度、断行与 `line-height: normal` 计算;
151
155
  `measureText`/`fontMetrics` 把它们暴露给测试。
152
156
 
157
+ 整形取舍:默认是简单整形器,不是完整的 OpenType 引擎。它覆盖拉丁/CJK/西里尔/
158
+ 希腊文、基础字距与逐码点回退,但不执行连字或复杂文种(阿拉伯/印度/泰文)整形,
159
+ 且 stb_truetype 只接受 TrueType 轮廓,不支持 CFF/OTF 或可变字体。该选择让
160
+ DOM-only 二进制约 3 MiB。可选的 **`shaping`** 链接特性会安装 HarfBuzz + FreeType
161
+ 后端(约 1.2 MiB),恢复完整 OpenType 整形与 CFF/OTF/可变字体支持;非 ASCII 文本
162
+ 会自动选中,也可用 `--feature shaping` 强制。
163
+
153
164
  ## 性能(M20)
154
165
 
155
166
  引擎是保留模式管线:一次 DOM 变更会重算样式、重新布局、重建显示列表并上传
@@ -168,6 +179,12 @@ shader 合成到场景上。全部十六种 CSS 模式(`multiply`、`screen`
168
179
  条目;某一代写满时丢弃**备用**代并切换过去,因此热路径上没有 LRU 记账。
169
180
  一个词只整形一次,之后每次布局和重绘都复用它。主字体查找也按
170
181
  (字体族类别,字号)缓存。
182
+ - **空写不生效。** 当节点已经显示该值时,`textContent` 与 `style.<属性>` 不做任何
183
+ 事:文档不会被标脏,也就没有重算样式、重新布局、重绘或上传。因此每帧都写入相同
184
+ 计时文本、相同血条宽度或相同 transform 的 HUD 不产生任何开销 —— 在此之前,每次
185
+ 赋值都会重建文本节点(一次分配,收集器随后还要清扫)或重写整条内联样式,并把
186
+ 文档标脏触发全文重算。`classList` 与 `removeAttribute` 早就是这样;`setAttribute`
187
+ 仍会无条件标脏。
171
188
  - **帧循环。** 只有文档发生变化(或首帧)时才把媒体/画布表与 DOM 对齐,不再每帧
172
189
  遍历整棵树。只有确实发生了事情才提交呈现(present)——DOM 变更、滚动、动画帧、
173
190
  过渡、新的视频/画布帧、expose/resize 事件——因此静态页面完全不获取 swapchain、
@@ -48,6 +48,9 @@ deferred` 才是页面自身造成的工作。调试"漏掉的失效"时可用
48
48
  动画帧回调,因此页面可以自行停止);
49
49
  - 只有在**仍有回调**时才重新排程,空闲页面会让事件循环排空并退出进程 ——
50
50
  这正是浏览器标签页的生命周期;
51
+ - 下一次 tick 排在**帧开始 + 16 ms**,而不是帧结束后再等 16 ms:帧自身耗时不再
52
+ 叠加到间隔上,10 ms 的帧以 16 ms 周期运行(而不是 26 ms),比 16 ms 更慢的页面
53
+ 则以全速运行,而不是每帧再落后一帧的时间;
51
54
  - 当 `xt_gui_run_active()` 为真(程序自己调用了 `run()`)时它会让路,避免同一
52
55
  窗口每 tick 被渲染两次;
53
56
  - `XT_GUI_AUTOCLOSE_MS=n` 让帧泵在 `n` 毫秒后退出,测试用它来运行不会自行
@@ -24,7 +24,7 @@ if (gl == null) {
24
24
  - 上下文记录到自己的 SDL_GPU 命令缓冲。`clear`/`draw*` 保持一个渲染 pass 打开;只有缓冲区/纹理上传或切换 framebuffer 才会结束它,并以 `LOAD` 开始新 pass,因此绘图缓冲在多次绘制之间保留,和 WebGL 一样;没有上传的绘制不会中断 pass。
25
25
  - 每帧一次,在页面自己的渲染 pass 之前,引擎提交所有 WebGL 命令缓冲。随后图像管线把颜色纹理当作普通 `PaintImage` 采样,没有 CPU 拷贝。
26
26
  - WebGL 原点在左下,SDL_GPU 渲染目标原点在左上,因此帧缓冲按自上而下存储:转换 `viewport`/`scissor`,`readPixels` 再把行翻回去,合成器看到的是正立的纹理。
27
- - 固定功能状态变化(`blendFunc`、`depthFunc`、`cullFace`、`colorMask` 等)会改变所需的 `SDL_GPUGraphicsPipeline`,因此管线按(程序、顶点布局、状态)惰性创建,并缓存在程序上。
27
+ - 固定功能状态变化(`blendFunc`、`depthFunc`、`cullFace`、`colorMask` 等)会改变所需的 `SDL_GPUGraphicsPipeline`,因此管线惰性创建并缓存在程序上。键是这次绘制的**内容**:程序、图元模式、顶点布局的哈希(属性位置、格式、偏移、缓冲 pitch 与输入速率)、反射出的固定功能状态、附件格式。它刻意**不**包含上下文的单调版本计数器(`attribs_version_`、`framebuffer_version_`)与 GPU 缓冲句柄:这些值在每次绑定 VAO、切换帧缓冲或重建缓冲时都会前进,却不改变管线;用它们做键会让每帧绑定多个布局的场景(three.js 每帧为每个几何体绑定一个 VAO)每帧重建全部管线 —— 实测每帧 248 次 `SDL_CreateGPUGraphicsPipeline`,且程序级缓存无界增长。`tests/e2e/gui-webgl-pipeline-cache.test.ts` 固定了稳态:布局相同、缓冲不同的两次绘制在首帧之后不再创建管线。
28
28
 
29
29
  ## 性能
30
30
 
@@ -118,7 +118,7 @@ transform feedback(入口为空操作:SDL_GPU 没有 transform feedback 阶
118
118
 
119
119
  管线按 SDL_GPU 设备接受的着色器格式创建:Vulkan 上用 **SPIR-V**(`SDL_GPU_SHADERFORMAT_SPIRV`,Windows/Linux 选择的后端),macOS 上用 **MSL**(`SDL_GPU_SHADERFORMAT_MSL`,Metal 后端)。两个后端共用同一个 GLSL 前端,因此在一个后端能编译的着色器在另一个上也能编译。如果设备的后端两种格式都不接受——Direct3D 12 需要 DXIL——`getContext("webgl")` 与 `getContext("webgl2")` 都会返回 `null`;2D canvas 与页面其余部分仍然正常。
120
120
 
121
- `npm run gui` 会拉取并构建 glslang 与 SPIRV-Cross,合并进 `gui.a` / `gui.lib`(见[打包与构建](./build.md));只用 2D canvas 或 DOM 的程序除了归档体积之外没有运行时开销。
121
+ `npm run gui` 会拉取并构建 glslang 并合并进 `gui.a` / `gui.lib`;SPIRV-Cross **只在 macOS 上**合并,因为其他 SDL_GPU 后端都不消费 MSL(见[打包与构建](./build.md))。两者都通过可选的 **`gpu` 链接特性**访问:编译器在程序可能调用 `getContext("webgl…")` 或使用 `mix-blend-mode` 时选中它,只有那时 bridge 才会把翻译器成员从 `gui.a` 里取出。WebGL context 与 DOM 绑定是单独的 **`webgl` 特性**,它依赖 `gpu`;只用 2D canvas 或 DOM 的程序既不链接 glslang、SPIRV-Cross,也不链接任何 `webgl_*` 成员(见[链接特性](./build.md#链接特性))。
122
122
 
123
123
  ## 测试
124
124
 
@@ -140,4 +140,4 @@ transform feedback(入口为空操作:SDL_GPU 没有 transform feedback 阶
140
140
 
141
141
  着色器改写器会把 three.js 的 `#pragma unroll_loop_start` 循环展开为常量索引(否则其采样器数组无法通过 Vulkan GLSL),`.js` 资源加载器则避免渲染器自带的展开器重复处理。`WebGLRenderer` 在本引擎真正的 WebGL 2 后端上原样运行,**不再打包 Canvas2D 回退**。已用 three.js r160 通过 SDL_GPU 验证:`MeshBasicMaterial`、`MeshStandardMaterial`、`MeshPhongMaterial`、`CanvasTexture`、线性雾、环境光/平行光/点光/聚光/半球光、`Sprite`、`Line`、`Points` 与 `InstancedMesh`。
142
142
 
143
- 本引擎子集之外的能力仍无法模拟:transform feedback 与 MSAA。立方体贴图/环境贴图、深度纹理、HDR/浮点渲染目标、压缩纹理与比较型 `sampler2DShadow` 采样都已可用(three.js 阴影贴图可在两个后端使用硬件深度比较)。需要 transform feedback 或 MSAA 的场景无法正确渲染;此前 Canvas2D 回退能显示的内容现在全部走 GPU。
143
+ 本引擎子集之外的能力仍无法模拟:transform feedback 与 MSAA。立方体贴图/环境贴图、深度纹理、HDR/浮点渲染目标、压缩纹理与比较型 `sampler2DShadow` 采样都已可用(three.js 阴影贴图可在两个后端使用硬件深度比较,Intel Mac 上的驱动问题见[已知问题](./known-issues.md))。需要 transform feedback 或 MSAA 的场景无法正确渲染;此前 Canvas2D 回退能显示的内容现在全部走 GPU。
package/doc/zh-CN/gui.md CHANGED
@@ -3,16 +3,18 @@
3
3
  > 语言 / Language:[English](../gui.md) | **简体中文**
4
4
 
5
5
  状态:**M20** —— 功能(M1–M15)已全部完成:HTML 解析、CSS 选择器匹配、层叠(cascade)、计算样式与布局(块级、行内、Flexbox 与 CSS 定位)均已就位,引擎还会**绘制**:它构建一个由矩形、图像与排版后的文本 run 组成的显示列表,并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器,`:hover`/`:focus` 会被动态匹配,`<img>` 依据其固有尺寸确定大小并从纹理绘制——位图(PNG/JPEG/…)与 SVG 文件皆可,后者按绘制尺寸光栅化,因此矢量图保持清晰——CSS transition 会为绘制属性做动画。**M16** 让内联 `<svg>` 子树获得同样的处理:子树被序列化回 SVG 文档,并按绘制设备尺寸光栅化,因此图标不再需要单独的文件。**M8** 增加了交互式 DOM:具有稳定标识的元素句柄、变更操作(`appendChild`、`textContent`、`classList`、`style` 等)以及支持捕获/冒泡的元素级事件。**M9** 会提前编译 `<script>` 主体(内联与 `<script src>`)——参见 `gui-scripts.md`。**M10** 增加 `requestAnimationFrame` 以及若干 DOM 辅助方法。**M11** 增加 `position: relative`/`absolute`/`fixed` 及其偏移,`examples/gui/pelican-bike`(一个可玩的 2D 游戏)就构建在它之上。**M12** 明确了 DOM 节点生命周期(哪些变更释放、哪些保留),并让引擎内存有界:参见[节点生命周期](./gui/dom.md)与[内存与 GC](./gui/runtime.md)。**M13** 真正播放
6
- `<video>`/`<audio>`——可选的 `media` 扩展用 vendored 的最小 FFmpeg 在主线程解码,
6
+ `<video>`/`<audio>`——可选的 **`media` 链接特性**用 vendored 的最小 FFmpeg 在主线程解码,
7
7
  视频帧走图像纹理路径、音频进入 SDL 流,DOM 媒体 API 暴露
8
- `play`/`pause`/`currentTime`/… 与媒体事件。只启用 `gui` 不会链接 FFmpeg。浏览器全局还带有真正可用的 `AudioContext`:`runtime/ext_gui/audio_mixer.cpp` 中的 48 kHz 混音器,以及 `decodeAudioData`(WAV 由引擎内解码,压缩格式经 `media`)——见 [GUI API](./gui/api.md#web-audio)。**M14** 增加了 `<canvas>`,配一个自研的 2D 软件光栅器(抗锯齿
8
+ `play`/`pause`/`currentTime`/… 与媒体事件。编译器会从程序里判断是否需要它
9
+ (`<video>`/`<audio>` 元素、`new Audio()`、`decodeAudioData`,或运行时拼出的 HTML),
10
+ 因此只做 DOM/CSS 的程序不会链接 FFmpeg。浏览器全局还带有真正可用的 `AudioContext`:`runtime/ext_gui/audio_mixer.cpp` 中的 48 kHz 混音器,以及 `decodeAudioData`(WAV 由引擎内解码,压缩格式经 `media` 特性)——见 [GUI API](./gui/api.md#web-audio)。**M14** 增加了 `<canvas>`,配一个自研的 2D 软件光栅器(抗锯齿
9
11
  填充、路径、文本与 `drawImage`),并经图像纹理路径上传——参见
10
12
  [Canvas](./gui/canvas.md)。**M15** 增加了 CSS `transform` /
11
13
  `transform-origin`:每个布局盒一个合成好的 `Matrix2D`,由显示列表一路带到
12
14
  渲染器,因此盒子(以及其中的文本、图像与子元素)可以被平移、缩放与旋转而
13
15
  不触发任何重排——再加上 `transition: transform`,这些姿态可以动画(自绘的示例
14
16
  `examples/gui/pelican-svg` 正是用它让矢量画动起来)。参见
15
- [布局](./gui/layout.md#变换m15)与[动画](./gui/animation.md#css-transformm15)。**M17** 增加了真正的 **WebGL 1.0**,**M18** 增加了 **WebGL 2.0**:`<canvas>.getContext("webgl2")` 接受 `#version 300 es` 着色器、顶点数组对象、实例化绘制与采样器对象,全部由内置 glslang 编译为 SPIR-V(Metal 上再由内置 SPIRV-Cross 转成 MSL)并通过 SDL_GPU 渲染,几何、光照、纹理采样与混合都在 GPU 上完成,页面直接合成颜色纹理而无须读回——见 [WebGL](./gui/webgl.md)。**M19** 补齐 CSS 装饰层:`@media` 查询、生成内容(`::before`/`::after`)、线性/径向/重复多层背景、`text-shadow`、`clip-path`、`mix-blend-mode`(通过离屏合成器)与 `filter` 颜色/阴影效果。`backdrop-filter` 仍需要背景快照,真正的组模糊也仍是近似——见[绘制](./gui/rendering.md#背景生成内容与特效m19)。**M20** 让大文档保持可交互:`@media` 每条规则只求值一次,布局与绘制共享一个有界的整形缓存,一帧只做(也只提交)变更所要求的工作——见[性能](./gui/rendering.md#性能m20)。本总览记录了锁定决策、架构、里程碑计划与当前进度;引擎本身按功能拆分在以上各页中。
17
+ [布局](./gui/layout.md#变换m15)与[动画](./gui/animation.md#css-transformm15)。**M17** 增加了真正的 **WebGL 1.0**,**M18** 增加了 **WebGL 2.0**:`<canvas>.getContext("webgl2")` 接受 `#version 300 es` 着色器、顶点数组对象、实例化绘制与采样器对象,全部由内置 glslang 编译为 SPIR-V(Metal 上再由内置 SPIRV-Cross 转成 MSL)并通过 SDL_GPU 渲染,几何、光照、纹理采样与混合都在 GPU 上完成,页面直接合成颜色纹理而无须读回——见 [WebGL](./gui/webgl.md)。glslang 是可选的 **`gpu` 链接特性**,与 `mix-blend-mode` 共享;WebGL context/DOM 绑定是单独的 **`webgl` 特性**(依赖 `gpu`),两者都不用时不链接。**M19** 补齐 CSS 装饰层:`@media` 查询、生成内容(`::before`/`::after`)、线性/径向/重复多层背景、`text-shadow`、`clip-path`、`mix-blend-mode`(通过离屏合成器)与 `filter` 颜色/阴影效果。`backdrop-filter` 仍需要背景快照,真正的组模糊也仍是近似——见[绘制](./gui/rendering.md#背景生成内容与特效m19)。**M20** 让大文档保持可交互:`@media` 每条规则只求值一次,布局与绘制共享一个有界的整形缓存,一帧只做(也只提交)变更所要求的工作——见[性能](./gui/rendering.md#性能m20)。本总览记录了锁定决策、架构、里程碑计划与当前进度;引擎本身按功能拆分在以上各页中。
16
18
 
17
19
  ## 目录
18
20
 
@@ -52,7 +54,8 @@
52
54
  | 4 | 引擎**非自托管**(它是 C/C++,不是 TS),但不得影响编译器的平台无关设计。以按平台预构建的归档形式交付,通过 `nativeObjects` 链接。 |
53
55
  | 5 | **事件循环是通用的**:运行时暴露一个通用主循环钩子与一个轮询原语;任何 GUI 特定的东西都不会进入 `runtime/`。 |
54
56
  | 6 | 核心对象模型支持**多窗口**。 |
55
- | 7 | 第三方底层库**静态链接进扩展归档**,使发布版保持自包含;链接时只额外加入操作系统框架。`gui.a` 携带 SDL3/FreeType/HarfBuzz,可选的 `media.a` 携带 FFmpeg,仅在 `--ext media` 时链接。 |
57
+ | 7 | 第三方底层库**静态链接进扩展归档**,使发布版保持自包含;链接时只额外加入操作系统框架。`gui.a` 携带 SDL3、用于可选 `shaping` 特性的 FreeType/HarfBuzz、glslang 和(仅 macOS)SPIRV-Cross;默认文本路径使用内置 stb_truetype。glslang 与 SPIRV-Cross 只有在编译器选中 **`gpu` 链接特性**时才会被从归档里取出。Metal 是唯一消费 MSL 的 SDL_GPU 后端,其他平台合并 SPIRV-Cross 只会多出约 2.5 MiB 没有任何驱动会请求的代码。WebGL context/DOM 代码是 **`webgl` 特性**(依赖 `gpu`),stb_image/NanoSVG 是 **`images` 特性**。可选的 `media.a` 携带 FFmpeg,仅在选中 **`media` 链接特性**时链接。所有特性都由程序的静态用法决定,可用 `--feature`/`--no-feature` 覆盖。 |
58
+ | 8 | **可选的重型部分做成链接特性,而不是独立扩展。** FFmpeg 与 glslang 由打包后的 HTML/CSS/TS 里可能用到的东西决定;只有特性启用时才会编译一个很小的 C bridge,它安装分发表并迫使链接器取出实现归档。这样用户仍然只看到 `gui` 一个扩展,而只做 DOM 的程序两套栈都不链接。 |
56
59
 
57
60
  ## 架构
58
61
 
@@ -72,12 +75,13 @@
72
75
  │
73
76
  ▼
74
77
  窗口 + 输入(SDL3)── 多窗口
75
- 文本(HarfBuzz + FreeType)── 字形图集 / SDF
78
+ 文本(stb_truetype)── 字形图集
76
79
  图像(stb_image;SVG 经 NanoSVG)
77
- 媒体 DOM + 音频 sink ── 可选的 media.a(FFmpeg)安装解码器
80
+ 媒体 DOM + 音频 sink ── 可选的 media 链接特性(media.a / FFmpeg)安装解码器
78
81
  ```
79
82
 
80
- 引擎从不与编译器通信。编译器只看到一个带有 `nativeObjects()`、`linkerFlags()` 和 `modules()` 的 `Extension`。
83
+ 引擎从不与编译器通信。编译器只看到一个带有 `nativeObjects()`、`linkerFlags()`、
84
+ `modules()` 和 `linkFeatures()` 的 `Extension`;FFmpeg 与 glslang 由后者按需选择。
81
85
 
82
86
  ## 技术栈(已确认)
83
87
 
@@ -85,14 +89,18 @@
85
89
  | --- | --- | --- |
86
90
  | 窗口 + 输入 + 多窗口 | **SDL3** | 跨平台窗口、HiDPI、IME、剪贴板、拖放、关闭/隐藏事件 |
87
91
  | GPU | **SDL_GPU**(SDL3) | 一条覆盖 Metal / Vulkan / D3D12 的渲染路径;避免三套后端 |
88
- | 文本整形 | **HarfBuzz** | 正确处理复杂文种的整形 |
89
- | 字形光栅化 | **FreeType** | 字形轮廓 → GPU 图集 / SDF |
92
+ | 文本整形 | **stb_truetype** 简单整形;可选 **`shaping`** 特性链接 HarfBuzz + FreeType | 默认让 DOM-only 二进制约 3 MiB;`shaping` 恢复连字/复杂文种整形 |
93
+ | 字形光栅化 | **stb_truetype**;仅 `shaping` 下用 FreeType | 默认 TrueType 轮廓 → 灰度图集 |
90
94
  | 图像 | 位图用 **stb_image**(vendored 头文件),SVG 用 **NanoSVG**(vendored 头文件) | 起步阶段用单头文件;SVG 文件按需光栅化 |
91
- | 视频 + 音频 | **FFmpeg**(静态 vendored,最小化构建,可选 `media` 扩展) | 解码常用容器/编码;不依赖 WebView 或平台媒体框架 |
95
+ | 视频 + 音频 | **FFmpeg**(静态 vendored,最小化构建,可选 `media` 链接特性) | 解码常用容器/编码;不依赖 WebView 或平台媒体框架 |
92
96
 
93
- 固定版本:SDL3 `release-3.2.10`、FreeType `2.13.3`、HarfBuzz `10.1.0`、
94
- FFmpeg `7.1`(供可选的 `media` 归档使用;可用 `SDL3_TAG` /
95
- `FREETYPE_VERSION` / `HARFBUZZ_VERSION` / `FFMPEG_VERSION` 覆盖)。
97
+ 固定版本:SDL3 `release-3.2.10`、FreeType `2.13.3`、HarfBuzz `10.1.0`
98
+ (供可选的 `shaping` 特性使用)、glslang `16.6.0`、SPIRV-Cross
99
+ `vulkan-sdk-1.4.313.0`、FFmpeg `7.1`(供可选的 `media` 归档使用;可用
100
+ `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` / `GLSLANG_VERSION` /
101
+ `SPIRV_CROSS_VERSION` / `FFMPEG_VERSION` 覆盖)。默认文本后端是内置的
102
+ `stb_truetype.h`;它只接受 TrueType 轮廓(不支持 CFF/OTF 或可变字体)。
103
+ `shaping` 特性会换成 HarfBuzz + FreeType,提供完整 OpenType 整形。
96
104
 
97
105
  如果否决 SDL3,备选是 **GLFW + OpenGL 3.3**(更简单,但 OpenGL 在 macOS 上
98
106
  已弃用,且不提供现代 GPU 抽象)。如果引擎用 Rust 编写,则用 **wgpu-native**。
@@ -118,10 +126,10 @@ FFmpeg `7.1`(供可选的 `media` 归档使用;可用 `SDL3_TAG` /
118
126
  4. **M4 — 绘制 + 文本 + 显示列表**
119
127
  - **M4a — 显示列表 + GPU 图形** ✅ 背景/边框显示列表、圆角矩形 SDL_GPU
120
128
  管线(`paint.*`、`renderer.*`)。
121
- - **M4b-1 — 文本技术栈 + 度量** ✅ HarfBuzz + FreeType 链接进 `gui.a`、
122
- 字体解析/缓存、供布局使用的基于整形的文本度量
123
- (`text.*`、`measureText`/`fontMetrics`)。
124
- - **M4b-2 — 字形渲染** ✅ FreeType 光栅化、共享的 shelf 打包字形图集、
129
+ - **M4b-1 — 文本技术栈 + 度量** ✅ 文本模块(`text.*`)与字体解析/缓存、
130
+ 供布局使用的基于整形的文本度量(`measureText`/`fontMetrics`);最初用
131
+ HarfBuzz + FreeType,现在用内置 stb_truetype。
132
+ - **M4b-2 — 字形渲染** ✅ stb_truetype 光栅化、共享的 shelf 打包字形图集、
125
133
  显示列表中的带纹理文本四边形与感知 HiDPI 的光栅缩放。渐变仍待完成。
126
134
  5. **M5 — 输入 + 事件** ✅
127
135
  - 命中测试(`LayoutTree::hitTest`)、带负载投递给 TS 处理器的指针/滚轮/
@@ -144,11 +152,12 @@ FFmpeg `7.1`(供可选的 `media` 归档使用;可用 `SDL3_TAG` /
144
152
  因此两者都会随现有 runtime 归档一起发布(`package-release` 复制整个
145
153
  `runtime/`),也会打进可选的 `@xbintsc/<os>-<arch>` npm 包。Windows x64
146
154
  已包含;Windows arm64 仍跳过。
147
- - `vendor/`(GUI 归档的 SDL3/FreeType/HarfBuzz,以及 `media` 的 FFmpeg,
155
+ - `vendor/`(GUI 归档的 SDL3/FreeType/HarfBuzz/glslang,以及 `media` 的 FFmpeg,
148
156
  缓慢的部分)按 OS/arch 缓存,以 `scripts/build-gui.ts` /
149
157
  `scripts/build-media.ts` 为键。Windows x64 有独立的源码 + FFmpeg 安装前缀
150
158
  缓存。
151
- - Windows x64 在 CI 中构建两个归档并链接一个 `gui,media` 程序;托管 runner
159
+ - Windows x64 在 CI 中构建两个归档并链接一个会触发 `media` 链接特性的 `gui`
160
+ 程序(另有一条显式 `--feature media` 的构建);托管 runner
152
161
  没有 GPU/Vulkan 驱动,因此 GUI/媒体示例的*运行*仍为试验性(失败只记录
153
162
  日志而不标注运行)。Windows arm64 仍跳过两个归档(见
154
163
  [待决问题](./gui/known-issues.md))。CI 通过
@@ -198,14 +207,16 @@ FFmpeg `7.1`(供可选的 `media` 归档使用;可用 `SDL3_TAG` /
198
207
  - `win.stats()` 暴露引擎计数器;e2e 覆盖见
199
208
  `tests/e2e/gui-retention.test.ts`(见[内存与 GC](./gui/runtime.md))。
200
209
  13. **M13 — 视频与音频** ✅
201
- - `<video>` / `<audio>` 通过可选的 `media` 扩展(`runtime/ext_media/media.cpp`)
202
- 使用静态 vendored 的最小 FFmpeg 解码,帧沿用现有图像管线上传到 GPU 纹理,
210
+ - `<video>` / `<audio>` 通过可选的 `media` **链接特性**(`runtime/ext_media/media.cpp`)
211
+ 使用静态 vendored 的最小 FFmpeg 解码。编译器从程序里检测到媒体用法时才编译
212
+ `media_bridge.c` 并链接 `media.a`,只做 DOM/CSS 的程序不会链接 FFmpeg。
213
+ 帧沿用现有图像管线上传到 GPU 纹理,
203
214
  音频由 GUI 的音频 sink 在主线程推送进 SDL 流,并在元素句柄上暴露 DOM
204
215
  媒体 API 与 `loadedmetadata`/`play`/`pause`/`ended`/`timeupdate`/`error`
205
216
  事件(`dom_api_media.cpp`、`dom_api_proto.cpp`)。由 TS + CSS 控制;没有
206
217
  内置控件。示例见 `examples/gui/media.*`;e2e 见
207
- `tests/e2e/gui-media.test.ts`(启用 `media`)与
208
- `tests/e2e/gui-media-disabled.test.ts`(不启用)。
218
+ `tests/e2e/gui-media.test.ts`(自动选中 `media`)与
219
+ `tests/e2e/gui-media-disabled.test.ts`(`--no-feature media`)。
209
220
  14. **M14 — `<canvas>` 2D** ✅
210
221
  - `<canvas>` 是一个替换元素(`xtgui::Canvas2D`、`layout.*`),
211
222
  `getContext("2d")` 句柄与绘制 API 位于 `dom_api_canvas.cpp`,自研的抗锯齿
@@ -295,9 +306,9 @@ FFmpeg `7.1`(供可选的 `media` 归档使用;可用 `SDL3_TAG` /
295
306
  Flexbox、`getBoundingClientRect`/`layoutTree`、e2e 覆盖。
296
307
  - **M4a** ✅ 显示列表(`paint.*`)与带 MSL 圆角矩形管线的 SDL_GPU 2D 渲染器
297
308
  (`renderer.*`)、`paintList`/`paintCount`、e2e 覆盖。
298
- - **M4b-1** ✅ FreeType + HarfBuzz 获取/构建/合并进 `gui.a`、带字体解析的文本
299
- 模块(`text.*`)、HarfBuzz 整形与 FreeType 度量、布局中的真实文本度量、
300
- `measureText`/`fontMetrics`、e2e 覆盖。
309
+ - **M4b-1** ✅ 文本模块(`text.*`)、字体解析、整形与度量、布局中的真实文本度量、
310
+ `measureText`/`fontMetrics`、e2e 覆盖。最初用 FreeType + HarfBuzz,现在用
311
+ stb_truetype(见技术栈表与 [构建](./gui/build.md#二进制体积)中的体积取舍)。
301
312
  - **M4b-2** ✅ `renderer.*` 中的字形图集 + 带纹理文本管线、`paint.*` 中的
302
313
  整形文本 run、`text.*` 中的 `xt_text_shape_run`/`xt_text_rasterize`、
303
314
  HiDPI 光栅缩放、e2e 覆盖。
@@ -347,13 +358,15 @@ FFmpeg `7.1`(供可选的 `media` 归档使用;可用 `SDL3_TAG` /
347
358
  失效;收集器的触发阈值改为跟随存活集,而不再只升不降。`win.stats()` 暴露
348
359
  引擎计数器,`tests/e2e/gui-retention.test.ts` 对其做断言;每帧重写精灵的游戏
349
360
  循环现在内存恒定(见[内存与 GC](./gui/runtime.md))。
350
- - **M13** ✅ `<video>` / `<audio>` 支持。可选的 `media` 扩展 vendored 并构建一个
351
- 最小化的静态 FFmpeg(`scripts/build-media.ts`),合并进 `media.a`;
361
+ - **M13** ✅ `<video>` / `<audio>` 支持。可选的 `media` **链接特性** vendored 并构建一个
362
+ 最小化的静态 FFmpeg(`scripts/build-media.ts`),合并进 `media.a`。编译器从程序里
363
+ 选中该特性后才编译 `media_bridge.c` 并链接 `media.a`;只做 DOM/CSS 的程序不会链接
364
+ FFmpeg。
352
365
  `runtime/ext_media/media.cpp` 在主线程把视频解码为 RGBA 帧、把音频解码为
353
366
  48 kHz 立体声 PCM,`runtime/ext_gui/gui_media.cpp` 持有播放器、实现 SDL 音频
354
367
  sink 并在每帧推进媒体时钟与事件,`renderer_image.cpp` 把每个新视频帧沿图像纹理
355
368
  路径上传,`dom_api_media.cpp` 在元素句柄上暴露 `play`/`pause`/`load` 与媒体
356
- 属性。`gui.a` 不含 FFmpeg;只启用 `media` 而不启用 `gui` 会被注册表拒绝。
369
+ 属性。`gui.a` 不含 FFmpeg。
357
370
  `examples/gui/media.*` 演示 TS + CSS 控件的模式,
358
371
  `tests/e2e/gui-media.test.ts` 对其做断言。
359
372
  - **M14** ✅ `<canvas>` 支持。新的替换元素(`layout.*`)从 `width`/`height`
@@ -28,6 +28,8 @@ xbintsc help 帮助
28
28
  --emit <kind> exe | obj | ir(默认 exe)
29
29
  -O0..-O3 优化级别(默认 -O2)
30
30
  --ext <names> 逗号分隔扩展(如 node)
31
+ --feature <names> 强制开启可选链接特性(media,gpu,images,shaping,webgl,all)
32
+ --no-feature <n> 即使检测到也不链接该可选特性
31
33
  --ext-native <m> 从 JSON manifest 注册 C++/Rust 扩展
32
34
  --config <path> 使用项目配置(默认自动查找 xbintsc.config.json)
33
35
  --no-config 不读取任何项目配置
@@ -2,10 +2,16 @@
2
2
 
3
3
  > 属于[已实现语法与功能](../implemented.md) · [English](../../implemented/extensions.md)
4
4
 
5
- 实现位置:`src/extensions/registry.ts`、`src/extensions/node/`
5
+ 实现位置:`src/extensions/registry.ts`、`src/extensions/node/`、`src/extensions/link-feature.ts`、`src/driver/usage.ts`、`src/driver/link-features.ts`
6
6
 
7
- - 扩展是普通对象:`runtimeSources()`(额外 C 源)、`linkerFlags()`(额外链接参数)、`builtins()`(全局标识符 → 运行时符号,统一 `(argc, argv)` ABI)与 `modules()`(导入说明符 → 命名导出 / 命名空间)。
8
- - `ExtensionRegistry`:注册 / 注销 / 查询 / 汇总 builtins、modules、runtime 源、链接参数。
7
+ - 扩展是普通对象:`runtimeSources()`(额外 C 源)、`linkerFlags()`(额外链接参数)、`builtins()`(全局标识符 → 运行时符号,统一 `(argc, argv)` ABI)、`modules()`(导入说明符 → 命名导出 / 命名空间)与 `linkFeatures()`(可选的重型能力)。
8
+ - `ExtensionRegistry`:注册 / 注销 / 查询 / 汇总 builtins、modules、runtime 源、链接参数与链接特性。
9
+ - **可选链接特性**(`media`、`gpu`、`images`、`shaping`、`webgl`):
10
+ - 特性声明 `runtimeSources()`(只在启用时编译的 C bridge)、`nativeObjects()`(只在启用时链接的归档)、`linkerFlags()`、可选的 `requires`(依赖的另一个特性)与 `used(usage)`。
11
+ - driver 从打包后的 AST 构造 `ProgramUsage`(`src/driver/usage.ts` 的 `collectUsage`):字符串字面量(含导入 HTML 与内联 CSS)、标识符/属性名、`getContext(...)` 的 kind,以及 markup 是否可能在运行时拼出。简单的 `const` 别名会被解析;无法解析的 markup 让程序走保守回退。
12
+ - `resolveLinkFeatures` 应用 `--feature` / `--no-feature`(以及 `all`),展开 `requires`,把自动检测到但不可用的特性报为 warning、把强制开启却不可用的报为 error,并返回要链接的 bridge/归档/参数。
13
+ - bridge 就是强引用:构造函数安装特性的分发表,其引用迫使链接器取出实现;没有 bridge 时表保持 null,实现成员永不被链接。
14
+ - 当前客户端:`media`(FFmpeg,`runtime/ext_media/media_bridge.c` + `media.a`)、`gpu`(glslang/SPIRV-Cross,`runtime/ext_gui/gpu_bridge.c` + `gui.a` 内的 `gpu_feature.cpp`)、`images`(stb_image/NanoSVG,`runtime/ext_gui/image_bridge.c` + `image_feature.cpp`)、`shaping`(HarfBuzz/FreeType,`runtime/ext_gui/text_bridge.c` + `text_hb.cpp`)与 `webgl`(context/DOM 绑定,`runtime/ext_gui/webgl_bridge.c` + `webgl_feature.cpp`,依赖 `gpu`)。
9
15
  - 内置核心扩展 `core`:暴露 `print`(映射 `xt_println`),始终注册。
10
16
  - Node 扩展 `node`:
11
17
  - 模块化组织:`src/extensions/node/fs/` + `runtime/ext_node/fs/read_file.c`
@@ -63,7 +63,8 @@ TypeScript 编译器。
63
63
 
64
64
  如果 npm 跳过了这个可选包(`--omit=optional`、不安装可选依赖的包管理器,或发布
65
65
  未覆盖的宿主平台),驱动会回退到从随包源码编译 C 运行时并缓存目标文件;这样仍能
66
- 工作,但首次构建更慢,`--ext gui` / `--ext media` 也需要归档存在。
66
+ 工作,但首次构建更慢,`--ext gui`(以及自动选择的 `media`/`gpu`/`images`/`shaping`/`webgl` 链接特性)也需要
67
+ 归档存在。
67
68
 
68
69
  ## 环境要求
69
70
 
@@ -372,7 +373,7 @@ jobs:
372
373
  | --- | --- | --- |
373
374
  | 需要 Node.js | 是,22+ | 否 |
374
375
  | 首次构建 | 链接可选平台包里的预编译运行时 | 直接链接预编译运行时 |
375
- | GUI / media 扩展 | Linux/macOS 与 Windows x64(发布为这些平台构建)包含 | Linux/macOS 与 Windows x64 压缩包包含 |
376
+ | GUI 引擎 + media 归档 | Linux/macOS 与 Windows x64(发布为这些平台构建)包含 | Linux/macOS 与 Windows x64 压缩包包含 |
376
377
  | 安装方式 | `npm install` + lockfile / provenance | 下载、校验 `.sha256`、解压 |
377
378
  | 编程 API | 有 | 无(仅 CLI) |
378
379
  | 交叉编译 | 否——只构建宿主平台 | 否——只构建宿主平台 |
@@ -407,7 +408,7 @@ npm 包通过可选平台包获得同一套预编译运行时,只有在跳过
407
408
  | 第一次构建很慢 | 可选包 `@xbintsc/<os>-<arch>` 被跳过(或该宿主没有预编译包),正在编译并缓存运行时 C 源码。用 `npm ls @xbintsc/<os>-<arch>` 检查,并去掉 `--omit=optional` 重新安装;`--time` 可确认。 |
408
409
  | 写 `.xbintsc/` 权限错误 | 用 `xbintsc_CACHE_DIR` 指向可写目录,或在可写目录中运行。 |
409
410
  | `module 'fs' is provided by the 'node' extension` | 加 `--ext node`,或在配置里写 `"extensions": ["node"]`。 |
410
- | `GUI native library not found` / `media native library not found` | 携带 `gui.a`/`gui.lib` 或 `media.a`/`media.lib` 的可选平台包被跳过,或该宿主没有预编译的 GUI/media 归档(Windows arm64)。去掉 `--omit=optional` 重新安装,或使用 Linux/macOS/Windows x64 发布压缩包,或从源码检出构建。 |
411
+ | `GUI native library not found` / `media native library not found` | 携带 `gui.a`/`gui.lib` 或 `media.a`/`media.lib` 的可选平台包被跳过,或该宿主没有预编译的 GUI/media 归档(Windows arm64)。去掉 `--omit=optional` 重新安装,或使用 Linux/macOS/Windows x64 发布压缩包,或从源码检出构建。自动检测到的 `media` 特性缺归档只会 warning;`--feature media` 才会报错。 |
411
412
  | `require("xbintsc")` 失败 | 包只提供 ESM;使用 `import`(或动态 `import()`)。 |
412
413
  | Windows 链接时报缺少 MSVC 库 | 在 Native Tools 命令提示符中运行,安装 VS C++ 生成工具,并检查 `npx xbintsc doctor`。 |
413
414
  | `npm ci --omit=dev` 后构建找不到 `xbintsc` | 在构建阶段安装 devDependencies,或把 `xbintsc` 移到 `dependencies`。 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xbintsc",
3
- "version": "0.5.45",
3
+ "version": "0.5.51",
4
4
  "description": "xbintsc - a TypeScript binary compiler (TypeScript -> LLVM IR -> native binary)",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -72,12 +72,12 @@
72
72
  "vitest": "^2.1.8"
73
73
  },
74
74
  "optionalDependencies": {
75
- "@xbintsc/linux-x64": "0.5.45",
76
- "@xbintsc/linux-arm64": "0.5.45",
77
- "@xbintsc/darwin-x64": "0.5.45",
78
- "@xbintsc/darwin-arm64": "0.5.45",
79
- "@xbintsc/win32-x64": "0.5.45",
80
- "@xbintsc/win32-arm64": "0.5.45"
75
+ "@xbintsc/linux-x64": "0.5.51",
76
+ "@xbintsc/linux-arm64": "0.5.51",
77
+ "@xbintsc/darwin-x64": "0.5.51",
78
+ "@xbintsc/darwin-arm64": "0.5.51",
79
+ "@xbintsc/win32-x64": "0.5.51",
80
+ "@xbintsc/win32-arm64": "0.5.51"
81
81
  },
82
82
  "engines": {
83
83
  "node": ">=22"
@@ -321,21 +321,28 @@ xt_value type_proto(const std::string &name) {
321
321
  return domapi::event_proto();
322
322
  }
323
323
  if (name == "AudioContext" || name == "webkitAudioContext") return xt_gui_audio_proto();
324
- if (name == "WebGLRenderingContext") return domapi::webgl_proto();
325
- if (name == "WebGL2RenderingContext") return domapi::webgl2_proto();
326
- if (name == "WebGLBuffer") return domapi::webgl_object_proto("buffer");
327
- if (name == "WebGLTexture") return domapi::webgl_object_proto("texture");
328
- if (name == "WebGLShader") return domapi::webgl_object_proto("shader");
329
- if (name == "WebGLProgram") return domapi::webgl_object_proto("program");
330
- if (name == "WebGLFramebuffer") return domapi::webgl_object_proto("framebuffer");
331
- if (name == "WebGLRenderbuffer") return domapi::webgl_object_proto("renderbuffer");
332
- if (name == "WebGLUniformLocation") return domapi::webgl_object_proto("uniform");
333
- if (name == "WebGLActiveInfo") return domapi::webgl_object_proto("info");
334
- if (name == "WebGLVertexArrayObject") return domapi::webgl_object_proto("vertexarray");
335
- if (name == "WebGLSampler") return domapi::webgl_object_proto("sampler");
336
- if (name == "WebGLQuery") return domapi::webgl_object_proto("query");
337
- if (name == "WebGLSync") return domapi::webgl_object_proto("sync");
338
- if (name == "WebGLTransformFeedback") return domapi::webgl_object_proto("transformfeedback");
324
+ if (name == "WebGLRenderingContext" || name == "WebGL2RenderingContext") {
325
+ const XtWebglApi *webgl = xt_webgl_api();
326
+ return webgl != nullptr ? webgl->proto(name == "WebGL2RenderingContext") : XT_UNDEFINED;
327
+ }
328
+ if (const XtWebglApi *webgl = xt_webgl_api(); webgl != nullptr) {
329
+ if (name == "WebGLBuffer") return webgl->object_proto("buffer");
330
+ if (name == "WebGLTexture") return webgl->object_proto("texture");
331
+ if (name == "WebGLShader") return webgl->object_proto("shader");
332
+ if (name == "WebGLProgram") return webgl->object_proto("program");
333
+ if (name == "WebGLFramebuffer") return webgl->object_proto("framebuffer");
334
+ if (name == "WebGLRenderbuffer") return webgl->object_proto("renderbuffer");
335
+ if (name == "WebGLUniformLocation") return webgl->object_proto("uniform");
336
+ if (name == "WebGLActiveInfo") return webgl->object_proto("info");
337
+ if (name == "WebGLVertexArrayObject") return webgl->object_proto("vertexarray");
338
+ if (name == "WebGLSampler") return webgl->object_proto("sampler");
339
+ if (name == "WebGLQuery") return webgl->object_proto("query");
340
+ if (name == "WebGLSync") return webgl->object_proto("sync");
341
+ if (name == "WebGLTransformFeedback") return webgl->object_proto("transformfeedback");
342
+ }
343
+ /* A WebGL host type with no linked WebGL feature is undefined, so feature
344
+ * probes take their fallback branch. */
345
+ if (name.rfind("WebGL", 0) == 0) return XT_UNDEFINED;
339
346
  if (name == "Path2D") return domapi::path2d_proto();
340
347
  if (name == "OffscreenCanvas") return domapi::offscreen_canvas_proto();
341
348
  if (name == "ImageBitmap") {
@@ -28,6 +28,8 @@ xt_value g_tick = XT_UNDEFINED;
28
28
  int g_tick_pending = 0;
29
29
  double g_tick_started_ms = 0;
30
30
  double g_tick_deadline_ms = 0;
31
+ /** When the frame being served started, for the next tick's delay. */
32
+ double g_tick_frame_started_ms = 0;
31
33
 
32
34
  xt_value browser_tick(xt_value self, xt_value env, int32_t argc, xt_value *argv);
33
35
 
@@ -39,7 +41,16 @@ void arm_tick(void) {
39
41
  g_tick = xt_closure_new((void *)browser_tick, 0, NULL);
40
42
  xt_gc_add_root(&g_tick);
41
43
  }
42
- xt_value args[2] = {g_tick, xt_number(16)};
44
+ /* Keep the frame *period* at 16 ms, measured from the start of the frame like
45
+ * a browser's vsync: scheduling 16 ms from the end made every frame cost its
46
+ * own duration on top of the delay, so a 10 ms frame ran at 38 fps and a
47
+ * 90 ms frame at 9 — with no way to ever catch up to the display. */
48
+ double elapsed = g_tick_frame_started_ms > 0.0
49
+ ? (double)SDL_GetTicks() - g_tick_frame_started_ms
50
+ : 16.0;
51
+ double delay = 16.0 - elapsed;
52
+ if (delay < 0.0) delay = 0.0;
53
+ xt_value args[2] = {g_tick, xt_number(delay)};
43
54
  g_tick_pending = 1;
44
55
  xt_set_timeout(2, args);
45
56
  }
@@ -50,6 +61,7 @@ xt_value browser_tick(xt_value self, xt_value env, int32_t argc, xt_value *argv)
50
61
  (void)argc;
51
62
  (void)argv;
52
63
  g_tick_pending = 0;
64
+ g_tick_frame_started_ms = (double)SDL_GetTicks();
53
65
  if (xt_gui_run_active()) return XT_UNDEFINED;
54
66
  if (g_tick_deadline_ms > 0 && (double)SDL_GetTicks() >= g_tick_deadline_ms) {
55
67
  /* Shared with `run()`: stop animating and let the program exit instead of
@@ -9,7 +9,7 @@
9
9
  *
10
10
  * The rasteriser is deliberately small and self-written (no Skia/Cairo): it
11
11
  * fills rectangles, polygons and flattened arcs with sub-scanline coverage
12
- * anti-aliasing, and blits FreeType glyph bitmaps for `fillText`. The pieces
12
+ * anti-aliasing, and blits stb_truetype glyph bitmaps for `fillText`. The pieces
13
13
  * live in `canvas_raster.cpp`; this header only exposes the object model.
14
14
  *
15
15
  * Canvas pixels are *not* touched by the garbage collector: a canvas is owned
@@ -5,7 +5,7 @@
5
5
  * nonzero winding rule and vertical sub-scanline sampling (4 samples per pixel
6
6
  * row) plus analytic horizontal coverage, which gives cheap anti-aliasing
7
7
  * without a full analytic rasteriser. Rectangles take a faster axis-aligned
8
- * path, and glyphs are composited from their FreeType coverage masks.
8
+ * path, and glyphs are composited from their stb_truetype coverage masks.
9
9
  */
10
10
 
11
11
  #include "canvas_internal.h"
@@ -1,7 +1,7 @@
1
1
  /*
2
2
  * xbintsc GUI engine — Canvas2D text drawing.
3
3
  *
4
- * `fillText`/`strokeText` shape a run with HarfBuzz and blit FreeType glyph
4
+ * `fillText`/`strokeText` shape a run with the shaper and blit stb_truetype glyph
5
5
  * coverage through the rasteriser. The state and path live in `canvas.h`; this
6
6
  * unit only owns the text entry points and the optional `maxWidth` condense.
7
7
  */
@@ -15,6 +15,7 @@
15
15
 
16
16
  #include "canvas.h"
17
17
  #include "css.h"
18
+ #include "image_api.h"
18
19
 
19
20
  #define METHOD(name) xt_value name(xt_value self, xt_value env, int32_t argc, xt_value *argv)
20
21
 
@@ -87,6 +88,8 @@ METHOD(node_get_context) {
87
88
  xtgui::Node *node = resolve_node(self, &win);
88
89
  if (mode == "webgl" || mode == "experimental-webgl" || mode == "webgl2") {
89
90
  const bool webgl2 = mode == "webgl2";
91
+ const XtWebglApi *webgl = xt_webgl_api();
92
+ if (webgl == nullptr) return XT_NULL;
90
93
  if (node == nullptr) return XT_NULL;
91
94
  if (!node->isElement() || !node->isTag("canvas")) return XT_NULL;
92
95
  if (xt_gui_canvas_find(win, node) != nullptr) return XT_NULL; // already a 2D canvas
@@ -95,13 +98,14 @@ METHOD(node_get_context) {
95
98
  const bool cached_webgl2 = value_truthy(xt_object_get_cstr(cached, "__xt_gl_webgl2"));
96
99
  return cached_webgl2 == webgl2 ? cached : XT_NULL;
97
100
  }
98
- xtgui::WebGLContext *context = xt_gui_webgl_get(win, node, webgl2);
99
- return webgl_context_handle(self, context);
101
+ void *context = webgl->get(win, node, webgl2);
102
+ return webgl->handle(self, context);
100
103
  }
101
104
  if (mode != "2d") return XT_NULL;
102
105
  if (node == nullptr) return xt_canvas_pending_context(self, win);
103
106
  if (!node->isElement() || !node->isTag("canvas")) return XT_NULL;
104
- if (xt_gui_webgl_find(win, node) != nullptr) return XT_NULL; // already a WebGL canvas
107
+ const XtWebglApi *webgl_api = xt_webgl_api();
108
+ if (webgl_api != nullptr && webgl_api->find(win, node) != nullptr) return XT_NULL; // already WebGL
105
109
  xt_value cached = xt_object_get_cstr(self, "__xt_gui_ctx");
106
110
  if (XT_IS_OBJECT(cached)) return cached;
107
111
  xtgui::Canvas2D *canvas = xt_gui_canvas_get(win, node);
@@ -483,12 +487,15 @@ METHOD(canvas_draw_image) {
483
487
  XtGuiWindow *win = nullptr;
484
488
  xt_value source_value = xt_arg(argc, argv, 0);
485
489
  const xtgui::Image *image = nullptr;
490
+ const XtImageApi *images = xt_image_api();
486
491
  if (XT_IS_STRING(source_value)) {
487
492
  /* Engine extension: the source may be a path or a `data:` URL itself, so a
488
493
  * data-URL bitmap/SVG can be drawn without an `<img>` element. */
489
494
  const std::string source_url(xt_string_data(source_value));
490
- image = xtgui::xt_image_load(source_url, raster_target(destination_width),
491
- raster_target(destination_height));
495
+ if (images != nullptr) {
496
+ image = images->load(source_url, raster_target(destination_width),
497
+ raster_target(destination_height));
498
+ }
492
499
  } else {
493
500
  /* An `OffscreenCanvas` (or a transferred one) has no DOM node; its bitmap
494
501
  * is reachable through the process-wide canvas id. */
@@ -503,9 +510,9 @@ METHOD(canvas_draw_image) {
503
510
  xtgui::Node *source = resolve_node(source_value, &win);
504
511
  if (source != nullptr && source->isElement() && source->isTag("img")) {
505
512
  const std::string *src = source->attr("src");
506
- if (src != nullptr) {
507
- image = xtgui::xt_image_load(*src, raster_target(destination_width),
508
- raster_target(destination_height));
513
+ if (src != nullptr && images != nullptr) {
514
+ image = images->load(*src, raster_target(destination_width),
515
+ raster_target(destination_height));
509
516
  }
510
517
  } else if (source != nullptr) {
511
518
  xtgui::Canvas2D *other = xt_gui_canvas_find(win, source);