sfml.js 1.0.0 → 1.1.0

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 (313) hide show
  1. package/README.ja.md +10 -9
  2. package/README.ko.md +10 -9
  3. package/README.md +10 -9
  4. package/README.zh-CN.md +10 -9
  5. package/binding.gyp +23 -16
  6. package/dist/audio/effect-processor.js +9 -3
  7. package/dist/audio/input-sound-file.js +41 -15
  8. package/dist/audio/listener.js +33 -11
  9. package/dist/audio/music.js +41 -18
  10. package/dist/audio/output-sound-file.js +4 -2
  11. package/dist/audio/playback-device.js +11 -3
  12. package/dist/audio/sound-buffer-recorder.js +8 -5
  13. package/dist/audio/sound-buffer.js +40 -17
  14. package/dist/audio/sound-file-factory.js +21 -9
  15. package/dist/audio/sound-file-reader.js +21 -7
  16. package/dist/audio/sound-recorder.js +36 -15
  17. package/dist/audio/sound-source.js +117 -40
  18. package/dist/audio/sound-stream.js +14 -5
  19. package/dist/audio/sound.js +9 -4
  20. package/dist/audio/value.js +42 -16
  21. package/dist/graphics/blend-mode.js +2 -1
  22. package/dist/graphics/boolean-vector.d.ts +1 -2
  23. package/dist/graphics/boolean-vector.js +19 -9
  24. package/dist/graphics/color.js +2 -1
  25. package/dist/graphics/convex-shape.js +7 -3
  26. package/dist/graphics/font.js +52 -23
  27. package/dist/graphics/glsl-matrix.js +8 -3
  28. package/dist/graphics/glsl.js +47 -16
  29. package/dist/graphics/glyph.js +27 -10
  30. package/dist/graphics/image.js +30 -14
  31. package/dist/graphics/rect.js +15 -8
  32. package/dist/graphics/render-states.js +18 -9
  33. package/dist/graphics/render-target.js +49 -23
  34. package/dist/graphics/render-texture.js +24 -12
  35. package/dist/graphics/render-window.js +6 -3
  36. package/dist/graphics/shader.js +67 -32
  37. package/dist/graphics/shape.js +25 -13
  38. package/dist/graphics/sprite.js +19 -9
  39. package/dist/graphics/stencil-mode.js +10 -6
  40. package/dist/graphics/swap.js +2 -1
  41. package/dist/graphics/text.js +123 -48
  42. package/dist/graphics/texture.js +48 -24
  43. package/dist/graphics/transform.js +29 -13
  44. package/dist/graphics/transformable.js +2 -1
  45. package/dist/graphics/vertex-array.js +40 -18
  46. package/dist/graphics/vertex-buffer.js +39 -19
  47. package/dist/graphics/vertex.js +6 -3
  48. package/dist/graphics/view.js +30 -14
  49. package/dist/index.d.ts +4 -4
  50. package/dist/internal/audio-codec-registry.js +12 -6
  51. package/dist/internal/audio-input-stream.js +2 -1
  52. package/dist/internal/audio-music-pump.js +58 -24
  53. package/dist/internal/audio-recorder-session.js +17 -7
  54. package/dist/internal/audio-worker-session.js +28 -10
  55. package/dist/internal/audio-worker.js +40 -21
  56. package/dist/internal/glsl-value.d.ts +3 -1
  57. package/dist/internal/glsl-value.js +18 -8
  58. package/dist/internal/graphics-state.js +29 -15
  59. package/dist/internal/input-stream.d.ts +3 -1
  60. package/dist/internal/input-stream.js +16 -7
  61. package/dist/internal/numeric-properties.js +2 -1
  62. package/dist/internal/render-states.js +2 -1
  63. package/dist/internal/scalar.js +22 -13
  64. package/dist/internal/shaped-glyph.d.ts +3 -1
  65. package/dist/internal/shaped-glyph.js +12 -4
  66. package/dist/internal/struct-view.d.ts +3 -1
  67. package/dist/internal/struct-view.js +3 -1
  68. package/dist/internal/transformable.js +2 -1
  69. package/dist/network/common.js +23 -11
  70. package/dist/network/dns.js +25 -17
  71. package/dist/network/ftp.js +43 -18
  72. package/dist/network/http.js +126 -56
  73. package/dist/network/ip-address.js +50 -25
  74. package/dist/network/packet.js +63 -25
  75. package/dist/network/sftp.js +175 -74
  76. package/dist/network/socket-selector.js +28 -14
  77. package/dist/network/socket.js +71 -30
  78. package/dist/network/tcp-listener.js +42 -19
  79. package/dist/network/tcp-socket.js +111 -53
  80. package/dist/network/tls-material.js +2 -1
  81. package/dist/network/udp-socket.js +68 -33
  82. package/dist/system/angle.js +2 -1
  83. package/dist/system/clock.js +4 -2
  84. package/dist/system/err.js +5 -2
  85. package/dist/system/file-input-stream.js +8 -4
  86. package/dist/system/input-stream.js +6 -3
  87. package/dist/system/operators.d.ts +1 -1
  88. package/dist/system/operators.js +90 -50
  89. package/dist/system/sleep.js +4 -2
  90. package/dist/system/time.js +12 -6
  91. package/dist/system/vector2.js +6 -7
  92. package/dist/system/vector3.js +11 -6
  93. package/dist/window/clipboard.js +2 -1
  94. package/dist/window/context.js +10 -5
  95. package/dist/window/cursor.js +2 -1
  96. package/dist/window/event.js +9 -5
  97. package/dist/window/mouse.js +4 -2
  98. package/dist/window/video-mode.js +2 -1
  99. package/dist/window/window.js +19 -12
  100. package/native/addon.cc +25 -12
  101. package/native/audio-binding.cc +266 -126
  102. package/native/audio-codec-binding.cc +147 -77
  103. package/native/audio-device-binding.cc +76 -49
  104. package/native/audio-file-binding.cc +116 -67
  105. package/native/audio-recorder-binding.cc +147 -98
  106. package/native/audio-recorder.h +1 -1
  107. package/native/audio-state.h +53 -30
  108. package/native/audio-stream-binding.cc +148 -94
  109. package/native/audio-stream.h +5 -4
  110. package/native/audio-worker-binding.cc +163 -81
  111. package/native/audio-worker.h +35 -19
  112. package/native/batch-drawable.cc +29 -16
  113. package/native/batch-drawable.h +11 -8
  114. package/native/context-binding.cc +40 -27
  115. package/native/context-settings.h +15 -8
  116. package/native/deferred-delete.cc +9 -6
  117. package/native/deferred-delete.h +7 -8
  118. package/native/error-stream-binding.cc +42 -28
  119. package/native/font-binding.cc +89 -48
  120. package/native/graphics-binding.cc +122 -72
  121. package/native/graphics-state.h +50 -36
  122. package/native/image-binding.cc +38 -24
  123. package/native/image-state.h +26 -18
  124. package/native/input-binding.cc +42 -27
  125. package/native/render-window-binding.cc +38 -23
  126. package/native/shader-binding.cc +115 -50
  127. package/native/shape-binding.cc +94 -49
  128. package/native/shape-state.h +18 -9
  129. package/native/shaped-glyph-storage.h +9 -5
  130. package/native/stream-binding.cc +143 -117
  131. package/native/system-binding.cc +17 -12
  132. package/native/text-binding.cc +68 -35
  133. package/native/text-state.h +25 -18
  134. package/native/texture-binding.cc +42 -33
  135. package/native/texture-resource.h +20 -12
  136. package/native/time-value.h +3 -1
  137. package/native/transformable-binding.cc +12 -6
  138. package/native/transformable-state.h +6 -6
  139. package/native/value-binding.h +46 -28
  140. package/native/value-layout.h +10 -10
  141. package/native/values-binding.cc +29 -23
  142. package/native/vertex-binding.cc +18 -12
  143. package/native/vertex-buffer-binding.cc +38 -24
  144. package/native/vertex-storage.h +2 -2
  145. package/native/view-data.h +4 -3
  146. package/native/window-binding.cc +75 -45
  147. package/native/window-event.h +20 -11
  148. package/native/window-owner.h +15 -12
  149. package/package.json +40 -48
  150. package/src/audio/effect-processor.ts +9 -3
  151. package/src/audio/input-sound-file.ts +108 -36
  152. package/src/audio/listener.ts +39 -13
  153. package/src/audio/music.ts +112 -47
  154. package/src/audio/output-sound-file.ts +40 -11
  155. package/src/audio/playback-device.ts +23 -8
  156. package/src/audio/sound-buffer-recorder.ts +35 -13
  157. package/src/audio/sound-buffer.ts +166 -58
  158. package/src/audio/sound-file-factory.ts +127 -49
  159. package/src/audio/sound-file-reader.ts +49 -15
  160. package/src/audio/sound-recorder.ts +100 -34
  161. package/src/audio/sound-source.ts +142 -45
  162. package/src/audio/sound-stream.ts +15 -5
  163. package/src/audio/sound.ts +12 -4
  164. package/src/audio/value.ts +89 -26
  165. package/src/graphics/blend-mode.ts +3 -1
  166. package/src/graphics/boolean-vector.ts +56 -26
  167. package/src/graphics/color.ts +3 -1
  168. package/src/graphics/convex-shape.ts +10 -3
  169. package/src/graphics/font.ts +171 -50
  170. package/src/graphics/glsl-matrix.ts +9 -3
  171. package/src/graphics/glsl.ts +81 -35
  172. package/src/graphics/glyph.ts +67 -26
  173. package/src/graphics/image.ts +119 -45
  174. package/src/graphics/rect.ts +56 -24
  175. package/src/graphics/render-states.ts +31 -14
  176. package/src/graphics/render-target.ts +197 -81
  177. package/src/graphics/render-texture.ts +36 -12
  178. package/src/graphics/render-window.ts +9 -3
  179. package/src/graphics/shader.ts +186 -61
  180. package/src/graphics/shape.ts +93 -35
  181. package/src/graphics/sprite.ts +64 -25
  182. package/src/graphics/stencil-mode.ts +12 -6
  183. package/src/graphics/swap.ts +3 -2
  184. package/src/graphics/text.ts +229 -74
  185. package/src/graphics/texture.ts +180 -61
  186. package/src/graphics/transform.ts +132 -47
  187. package/src/graphics/transformable.ts +3 -1
  188. package/src/graphics/vertex-array.ts +87 -35
  189. package/src/graphics/vertex-buffer.ts +97 -33
  190. package/src/graphics/vertex.ts +9 -3
  191. package/src/graphics/view.ts +59 -21
  192. package/src/index.ts +101 -23
  193. package/src/internal/audio-codec-registry.ts +18 -6
  194. package/src/internal/audio-input-stream.ts +6 -2
  195. package/src/internal/audio-music-pump.ts +116 -41
  196. package/src/internal/audio-native.ts +249 -96
  197. package/src/internal/audio-recorder-session.ts +68 -24
  198. package/src/internal/audio-worker-session.ts +65 -21
  199. package/src/internal/audio-worker.ts +85 -41
  200. package/src/internal/glsl-value.ts +26 -11
  201. package/src/internal/graphics-state.ts +57 -20
  202. package/src/internal/input-stream.ts +23 -10
  203. package/src/internal/native.ts +252 -99
  204. package/src/internal/numeric-properties.ts +2 -1
  205. package/src/internal/render-states.ts +3 -1
  206. package/src/internal/scalar.ts +33 -14
  207. package/src/internal/shaped-glyph.ts +25 -12
  208. package/src/internal/struct-view.ts +40 -13
  209. package/src/internal/transformable.ts +3 -1
  210. package/src/network/common.ts +35 -11
  211. package/src/network/dns.ts +95 -38
  212. package/src/network/ftp.ts +129 -47
  213. package/src/network/http.ts +232 -77
  214. package/src/network/ip-address.ts +118 -48
  215. package/src/network/packet.ts +161 -54
  216. package/src/network/sftp.ts +498 -168
  217. package/src/network/socket-selector.ts +66 -26
  218. package/src/network/socket.ts +133 -46
  219. package/src/network/tcp-listener.ts +78 -29
  220. package/src/network/tcp-socket.ts +240 -95
  221. package/src/network/tls-material.ts +6 -2
  222. package/src/network/udp-socket.ts +147 -53
  223. package/src/system/angle.ts +3 -1
  224. package/src/system/clock.ts +12 -4
  225. package/src/system/err.ts +5 -2
  226. package/src/system/file-input-stream.ts +12 -4
  227. package/src/system/input-stream.ts +9 -3
  228. package/src/system/operators.ts +290 -115
  229. package/src/system/sleep.ts +6 -2
  230. package/src/system/time.ts +18 -6
  231. package/src/system/timeout-with-predicate.ts +19 -8
  232. package/src/system/vector2.ts +101 -49
  233. package/src/system/vector3.ts +85 -36
  234. package/src/window/clipboard.ts +3 -1
  235. package/src/window/context.ts +15 -5
  236. package/src/window/cursor.ts +3 -1
  237. package/src/window/event.ts +26 -12
  238. package/src/window/mouse.ts +6 -2
  239. package/src/window/video-mode.ts +3 -1
  240. package/src/window/window.ts +119 -37
  241. package/test/native/audio-probes.cc +74 -36
  242. package/test/native/deferred-delete-probes.cc +17 -11
  243. package/test/native/drawable-probes.cc +70 -36
  244. package/test/native/exception-probes.cc +14 -9
  245. package/test/native/image-probes.cc +20 -10
  246. package/test/native/matrix-probes.cc +8 -4
  247. package/test/native/network-oracle.cc +17 -11
  248. package/test/native/render-texture-probes.cc +33 -24
  249. package/test/native/shader-probes.cc +9 -9
  250. package/test/native/shape-probes.cc +37 -23
  251. package/test/native/sprite-probes.cc +41 -25
  252. package/test/native/system-probes.cc +58 -35
  253. package/test/native/text-probes.cc +77 -44
  254. package/test/native/texture-probes.cc +43 -26
  255. package/test/native/time-probes.cc +18 -12
  256. package/test/native/transform-probes.cc +15 -10
  257. package/test/native/transformable-probes.cc +23 -17
  258. package/test/native/value-oracle.h +9 -4
  259. package/test/native/value-probes.cc +31 -23
  260. package/test/native/vertex-array-probes.cc +22 -14
  261. package/test/native/vertex-buffer-probes.cc +28 -17
  262. package/test/native/view-probes.cc +29 -17
  263. package/test/native/window-probes.cc +66 -33
  264. package/tools/ensure-sfml.cjs +9 -0
  265. package/tools/generate-network-constants.cjs +11 -6
  266. package/tools/generate-window-constants.cjs +31 -12
  267. package/docs/README.ja.md +0 -30
  268. package/docs/README.ko.md +0 -30
  269. package/docs/README.md +0 -30
  270. package/docs/README.zh-CN.md +0 -30
  271. package/docs/api.ja.md +0 -84
  272. package/docs/api.ko.md +0 -84
  273. package/docs/api.md +0 -81
  274. package/docs/api.zh-CN.md +0 -81
  275. package/docs/audio.ja.md +0 -249
  276. package/docs/audio.ko.md +0 -251
  277. package/docs/audio.md +0 -252
  278. package/docs/audio.zh-CN.md +0 -252
  279. package/docs/concepts.ja.md +0 -130
  280. package/docs/concepts.ko.md +0 -130
  281. package/docs/concepts.md +0 -131
  282. package/docs/concepts.zh-CN.md +0 -131
  283. package/docs/development.ja.md +0 -144
  284. package/docs/development.ko.md +0 -144
  285. package/docs/development.md +0 -146
  286. package/docs/development.zh-CN.md +0 -146
  287. package/docs/getting-started.ja.md +0 -154
  288. package/docs/getting-started.ko.md +0 -154
  289. package/docs/getting-started.md +0 -156
  290. package/docs/getting-started.zh-CN.md +0 -156
  291. package/docs/graphics.ja.md +0 -256
  292. package/docs/graphics.ko.md +0 -254
  293. package/docs/graphics.md +0 -255
  294. package/docs/graphics.zh-CN.md +0 -257
  295. package/docs/network.ja.md +0 -214
  296. package/docs/network.ko.md +0 -216
  297. package/docs/network.md +0 -218
  298. package/docs/network.zh-CN.md +0 -218
  299. package/docs/system.ja.md +0 -169
  300. package/docs/system.ko.md +0 -171
  301. package/docs/system.md +0 -173
  302. package/docs/system.zh-CN.md +0 -173
  303. package/docs/window.ja.md +0 -138
  304. package/docs/window.ko.md +0 -140
  305. package/docs/window.md +0 -141
  306. package/docs/window.zh-CN.md +0 -141
  307. package/native/exception-boundary.h +0 -97
  308. package/native/numeric-fields.h +0 -96
  309. package/native/shared-handle.h +0 -107
  310. package/test/tsconfig.json +0 -8
  311. package/tools/configure-lsp.cjs +0 -23
  312. package/tools/lib_downloader.cjs +0 -92
  313. package/tools/lib_downloader_urls.cjs +0 -23
@@ -1,257 +0,0 @@
1
- # Graphics
2
-
3
- [English](graphics.md) · **简体中文** · [日本語](graphics.ja.md) · [한국어](graphics.ko.md)
4
-
5
- > 从 Image/Texture 准备素材,用 Sprite、Shape、Text 或顶点组织场景,再交给 RenderWindow 或 RenderTexture 绘制。
6
-
7
- [API 导航](api.zh-CN.md) · [窗口与事件](window.zh-CN.md) · [绘制快照](concepts.zh-CN.md#draw-snapshots)
8
-
9
- ## Image:CPU 像素
10
-
11
- Image 保存 RGBA8 像素,`.pixels` 是直接映射 Native 分配的 Uint8Array:
12
-
13
- ```typescript
14
- import { Image, Color, Vector2u } from 'sfml.js';
15
-
16
- const image = new Image(new Vector2u(64, 64), Color.White);
17
- image.setPixel(new Vector2u(0, 0), Color.Red);
18
- image.pixels[3] = 128;
19
- if (!await image.saveToFile('image.png')) throw new Error('Cannot save image');
20
- ```
21
-
22
- | 接口 | 行为 |
23
- | --- | --- |
24
- | 空构造、尺寸与颜色、尺寸与 RGBA 字节、复制构造 | 创建独立像素资源 |
25
- | `loadFromFile/Memory/Stream()` | 异步加载,返回 boolean |
26
- | `saveToFile()`/`saveToMemory(format)` | 异步编码;返回 boolean/字节或 undefined |
27
- | `getSize()`、`getPixel()`、`setPixel()` | 尺寸与单像素操作 |
28
- | `pixels`/`getPixelsPtr()` | 可写视图/只读类型视图,后者在空图像时为 undefined |
29
- | `resize(size, color?)` | 重新分配并填充,尺寸相同也不保留旧内容 |
30
- | `copy()`、`createMaskFromColor()`、`flipHorizontally()`、`flipVertically()` | 区域复制、遮罩与翻转 |
31
-
32
- 原始 RGBA 输入长度必须为宽 × 高 × 4,构造时复制。成功重载或 resize 后,旧视图继续保活旧分配;失败加载保留当前图像。不要分离或调整像素 buffer。
33
-
34
- 异步内存加载在调用时复制编码输入;异步保存复制调用时的像素。读取、解码和编码在后台执行,但快照仍有主线程成本。输入流使用规则见 [System](system.zh-CN.md#input-streams)。
35
-
36
- ## Texture:GPU 纹理
37
-
38
- ```typescript
39
- import { Texture, Sprite } from 'sfml.js';
40
-
41
- const texture = new Texture();
42
- if (!await texture.loadFromFile('sprite.png')) {
43
- throw new Error('Cannot load sprite.png');
44
- }
45
- texture.setSmooth(true);
46
- const sprite = new Sprite(texture);
47
- ```
48
-
49
- 空构造适合异步加载;`new Texture(size)` 分配 GPU 存储,`new Texture(image)` 上传已解码图像,`new Texture(sourceTexture)` 复制 GPU 内容。后两种不执行文件读取。
50
-
51
- | 接口 | 行为 |
52
- | --- | --- |
53
- | `loadFromFile/Memory/Stream(source, sRgb?, area?)` | 异步解码、调用线程上传;area 为 IntRect |
54
- | `loadFromImage(image, sRgb?, area?)` | 同步上传,返回 boolean |
55
- | `update(pixels)`/`update(pixels, size, dest)` | 上传全部/局部 RGBA |
56
- | `update(imageOrTextureOrWindow, dest?)` | 复制源内容 |
57
- | `resize(size, sRgb?)` | 重建存储,成功后像素未定义 |
58
- | `copyToImage()` | 同步 GPU 读回,得到独立 Image |
59
- | `assign(source)`/`swap(other)` | 独立复制/交换内容,保留目标对象身份 |
60
- | `setSmooth()`/`setRepeated()` | 平滑/重复采样 |
61
- | `generateMipmap()` | 生成 mipmap;更新内容后需重新生成 |
62
- | `getNativeHandle()`/`Texture.bind()` | OpenGL 名称/当前上下文绑定 |
63
- | `Texture.getMaximumSize()` | 当前设备的最大纹理边长 |
64
-
65
- 加载失败保留旧内容。多个加载按完成顺序生效,确定顺序时逐次 await。GPU 上传和读回是同步操作,大纹理会占用调用线程。
66
-
67
- 局部 update 不缩放或裁剪,目的区域越界会抛错。加载的裁剪矩形任一尺寸为零时使用全图;其他非空区域按图像范围调整,非法负尺寸或起点越界被拒绝。
68
-
69
- 纹理尺寸变化不会自动修改 Sprite 的纹理矩形,需要全图时调用 `sprite.setTexture(texture, true)`。修改纹理内容或采样设置前,绑定提交依赖旧状态的绘制。
70
-
71
- ## Sprite 与变换
72
-
73
- Sprite 必须从 Texture 或其他 Sprite 构造。复制 Sprite 会复制外观和变换,并引用同一纹理。
74
-
75
- | 接口 | 语义 |
76
- | --- | --- |
77
- | `setPosition()`/`move()` | 位置及相对移动,Vector2f |
78
- | `setRotation()`/`rotate()` | 角度及相对旋转,Angle |
79
- | `setScale()`/`scale()`、`setOrigin()` | 缩放与原点,Vector2f |
80
- | `getTransform()`/`getInverseTransform()` | 缓存的只读矩阵,查询时更新 |
81
- | `setTexture(texture, resetRect?)` | 切换纹理,默认保留纹理矩形 |
82
- | `setTextureRect(rect)` | 复制矩形,负尺寸可用于翻转 |
83
- | `setColor(color)` | 颜色与 alpha 调制 |
84
- | `getLocalBounds()`/`getGlobalBounds()` | 局部/自身变换后的轴对齐边界 |
85
-
86
- 变换 getter 的位置、缩放、原点和角度返回独立值。修改后要通过 setter 写回。`getTextureRect()` 则返回只读实时视图,后续 setter 会更新它。
87
-
88
- global bounds 不包括 draw 传入的外层 RenderStates。Shape 和 Text 也提供同样的变换接口。
89
-
90
- ## Shape
91
-
92
- ```typescript
93
- import { CircleShape, RectangleShape, Vector2f, Color } from 'sfml.js';
94
-
95
- const circle = new CircleShape({ radius: 24, pointCount: 48 });
96
- circle.setFillColor(Color.Cyan);
97
- circle.setOutlineColor(Color.White);
98
- circle.setOutlineThickness(2);
99
- const rectangle = new RectangleShape(new Vector2f(120, 40));
100
- rectangle.setPosition(new Vector2f(60, 20));
101
- ```
102
-
103
- ConvexShape 接受点数,随后用 `setPoint()` 填入凸多边形顶点。三类形状均支持同类复制构造、纹理、填充、轮廓和边界查询。
104
-
105
- 自定义形状继承 Shape,实现 `getPointCount()` 和 `getPoint()`,点集变化后调用 protected `update()`。点集必须满足凸形状要求,update 生成几何,提交绘制时不会再次查询 JS 点方法。
106
-
107
- 轮廓厚度可以为负;miter limit 的默认值为 10,最小为 1。改变几何、轮廓厚度或 miter limit 前,会先提交引用旧几何的命令。
108
-
109
- ## Font、Glyph 与 Text
110
-
111
- ```typescript
112
- import { Font, Text, TextStyle, LineAlignment, Color, Vector2f } from 'sfml.js';
113
-
114
- const font = new Font();
115
- if (!await font.openFromFile('font.ttf')) throw new Error('Cannot open font');
116
- const text = new Text({ font, string: 'Hello\nSFML', characterSize: 30 });
117
- text.setPosition(new Vector2f(20, 30));
118
- text.setStyle(TextStyle.Bold);
119
- text.setLineAlignment(LineAlignment.Center);
120
- text.setFillColor(Color.White);
121
- ```
122
-
123
- Font 的加载方法为 `openFromFile/Memory/Stream()`,不是 loadFromFile。加载失败保留旧字体。内存输入由 Native 持有;文件方式在字体使用期间应保持源文件可用。
124
-
125
- Font 提供字形、字偶距、行间距、上下伸部与下划线度量。`getGlyph()` 按 Unicode 码点查询,`getGlyphById()` 按字体内部编号查询;`getTexture(size)` 返回随字形增长的只读图集。
126
-
127
- Text 支持字体、字符串、字号、间距、填充、轮廓、样式、行对齐、字素分组及文字方向配置。`getShapedGlyphs()` 返回字形列表,`setGlyphPreProcessor()` 可按字形调整外观。
128
-
129
- `getShapedGlyphs()` 和预处理回调的 cluster 使用 JS UTF-16 下标,例如 `A😀中` 为 0、1、3;已弃用的 `findCharacterPos()` 使用 Unicode 码点索引。预处理回调中不能再次修改当前 Text 的排版属性或查询几何。
130
-
131
- `getVertexData()` 与 `getOutlineVertexData()` 提供可编辑顶点。修改影响后续 draw,重新排版会生成新几何;旧视图保活原分配。每次 draw 保存顶点快照。
132
-
133
- ## View 与坐标
134
-
135
- View 控制中心、尺寸、旋转、viewport 和 scissor:
136
-
137
- ```typescript
138
- import { RenderTexture, View, Vector2u, Vector2f } from 'sfml.js';
139
-
140
- const target = new RenderTexture(new Vector2u(800, 600));
141
- const camera = new View(target.getDefaultView());
142
- camera.move(new Vector2f(100, 0));
143
- camera.zoom(0.5);
144
- target.setView(camera);
145
- ```
146
-
147
- setView 按值复制。`getView()` 与 `getDefaultView()` 返回稳定只读引用;需要修改时复制为 View。
148
-
149
- `mapPixelToCoords(Vector2i, view?)` 将像素转换为世界坐标,`mapCoordsToPixel(Vector2f, view?)` 反向转换。省略 view 时使用当前视图。
150
-
151
- viewport 与 scissor 使用相对整个目标的归一化矩形。scissor 必须位于 `[0, 1]`,同时影响 draw、clear 和 clearStencil。
152
-
153
- ## RenderTexture 与离屏合成
154
-
155
- ```typescript
156
- import { RenderTexture, Vector2u, Sprite, Color } from 'sfml.js';
157
-
158
- const source = new RenderTexture(new Vector2u(64, 64));
159
- source.clear(Color.Red);
160
- source.display();
161
-
162
- const output = new RenderTexture(new Vector2u(128, 128));
163
- output.clear();
164
- output.draw(new Sprite(source.getTexture()));
165
- output.display();
166
- await output.getTexture().copyToImage().saveToFile('offscreen.png');
167
- ```
168
-
169
- `getTexture()` 返回稳定的只读 GPU 纹理视图,不复制像素,也不隐式 display。`flush()` 仅提交绘制,采样新内容前仍需 display。不能在同一目标上直接采样自身纹理。
170
-
171
- `resize(size, settings?)` 成功后重置当前和默认视图,像素内容未定义;失败保留原目标。已有纹理视图继续有效,但关联 Sprite 的纹理矩形需按需重设。
172
-
173
- ContextSettings 支持 depthBits、stencilBits、antiAliasingLevel、majorVersion、minorVersion、attributeFlags、sRgbCapable。实际能力受驱动影响,SFML Graphics 需要兼容 OpenGL 上下文。
174
-
175
- ## Drawable 与 RenderStates
176
-
177
- 自定义组合对象继承 Drawable,实现同步 protected draw。每次调用会收到独立 RenderStates 值副本,资源引用仍共享:
178
-
179
- ```typescript
180
- import { Drawable, RenderTarget, RenderStates, Transformable } from 'sfml.js';
181
-
182
- class Group extends Drawable {
183
- /** 组合对象的本地变换。 */
184
- readonly pose = new Transformable();
185
-
186
- /** 保留按顺序绘制的子对象。 */
187
- constructor(readonly children: Drawable[]) { super(); }
188
-
189
- /** 将本地变换组合到父状态后绘制各子对象。 */
190
- protected draw(target: RenderTarget, states: RenderStates): void {
191
- states.transform.combine(this.pose.getTransform());
192
- for (const child of this.children) target.draw(child, states);
193
- }
194
- }
195
- ```
196
-
197
- | RenderStates 字段 | 默认值 |
198
- | --- | --- |
199
- | transform | 单位变换 |
200
- | blendMode | BlendAlpha |
201
- | stencilMode | 默认 StencilMode |
202
- | coordinateType | CoordinateType.Pixels |
203
- | texture/shader | null |
204
-
205
- draw 接受 RenderStates、状态选项,或单独的 Transform、Texture、Shader、BlendMode、StencilMode 等。Sprite 与 Shape 使用自身纹理和坐标模式。
206
-
207
- 模板遮罩需要目标提供 stencilBits。`clear(color, stencil)` 同时清颜色与模板,`clearStencil()` 只清模板。BlendMode 提供 Alpha、Add、Multiply、Min、Max、None 预设。
208
-
209
- ## 顶点与 GPU 缓冲
210
-
211
- ```typescript
212
- import { VertexArray, Vertex, PrimitiveType, Vector2f, Color } from 'sfml.js';
213
-
214
- const triangle = new VertexArray(PrimitiveType.Triangles, 3);
215
- triangle.setVertex(0, new Vertex(new Vector2f(10, 10), Color.Red));
216
- triangle.setVertex(1, new Vertex(new Vector2f(100, 10), Color.Green));
217
- triangle.setVertex(2, new Vertex(new Vector2f(10, 100), Color.Blue));
218
- triangle.getVertex(1).position.x = 120;
219
- ```
220
-
221
- VertexArray 支持 get/setVertex、append、resize、clear、getBounds 和迭代。draw 立即保存连续顶点快照;之后修改或扩容不会改变已录制画面。结构修改后重新取得成员,迭代期间不要修改结构。
222
-
223
- SFML 3 支持 Points、Lines、LineStrip、Triangles、TriangleStrip、TriangleFan。多个方块可用三角形组织进一个 VertexArray,从而减少实际 SFML draw 次数。
224
-
225
- VertexBuffer 把顶点保存在 GPU;先 `create(count)`,再 `update(vertices)`,检查两者的布尔返回值。Usage 提供 Stream、Dynamic、Static。范围绘制使用 `target.draw(buffer, firstVertex, vertexCount, states?)`。
226
-
227
- `assign()` 深拷贝 GPU 数据、图元和 usage;`update(sourceBuffer)` 复制数据并保留目标图元和 usage;`swap()` 交换资源。修改存储前提交旧绘制。GL 名称可能变化,使用前重新获取。
228
-
229
- ## Shader、Transform 与 GLSL
230
-
231
- Shader 使用异步 `loadFromFile/Memory/Stream()`,支持单阶段或 vertex/fragment/geometry 组合。成功重载替换程序并清空 uniform 状态,失败保留旧程序。
232
-
233
- `setUniform()` 接受 number、boolean、Glsl 向量/矩阵、Texture 和 `Shader.CurrentTexture`。number 默认 float,整数使用第三个参数 `'int'`。uniform 修改前提交已有绘制。
234
-
235
- `Glsl.Vec2/3/4`、`Ivec2/3/4`、`Bvec2/3/4` 对应 GLSL 向量;Mat3/Mat4 从数组、同尺寸矩阵或 Transform 构造,`.array` 是列主序 Float32Array。四维向量与矩阵不提供通用向量算术运算符。
236
-
237
- Transform 支持平移、旋转、缩放与 combine,原位修改并返回自身。组合为右乘,`translate(...).scale(...)` 对点先缩放再平移。getMatrix 返回只读实时数组;奇异矩阵求逆返回独立单位变换。
238
-
239
- 通过 `Shader.isAvailable()`、`isGeometryAvailable()` 和 `VertexBuffer.isAvailable()` 查询能力。直接使用 Texture/Shader/VertexBuffer 的 bind 前,先显式提交已有 SFML 命令。
240
-
241
- ## 示例与性能验证
242
-
243
- [示例目录](../examples/README.zh-CN.md) 提供纹理、精灵、文字、顶点、组合绘制和离屏合成的独立入口。
244
-
245
- 构建后运行 `tools/benchmark-image.cjs`、`tools/benchmark-drawable.cjs`、`tools/benchmark-vertex-array.cjs` 可测当前实现。基准中的调用线程时间包含记录、提交和驱动工作,不能直接当作 GPU 时间或真实游戏帧率。
246
-
247
- <a id="sfml-cpp-reference"></a>
248
-
249
- ## SFML C++ 参考
250
-
251
- | 主题 | 上游类 |
252
- | --- | --- |
253
- | 图片与绘制对象 | [Image](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Image.html)、[Texture](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Texture.html)、[Sprite](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Sprite.html)、[Shape](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Shape.html) |
254
- | 文字与相机 | [Font](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Font.html)、[Text](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Text.html)、[View](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1View.html) |
255
- | 绘制与几何 | [RenderTarget](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1RenderTarget.html)、[RenderTexture](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1RenderTexture.html)、[Drawable](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Drawable.html)、[Shader](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Shader.html)、[VertexArray](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1VertexArray.html)、[VertexBuffer](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1VertexBuffer.html) |
256
-
257
- 上游文档可用于理解纹理坐标、变换、相机、混合与图元等渲染概念。JS 的资源构造、Promise 加载及 draw 快照与提交时机按本指南执行;C++ 示例中的同步文件构造不直接适用于本绑定。
@@ -1,214 +0,0 @@
1
- # Network
2
-
3
- [English](network.md) / [简体中文](network.zh-CN.md) / **日本語** / [한국어](network.ko.md)
4
-
5
- > Packet でメッセージを定義し、TCP/UDP で転送するか、HTTP、FTP、SFTP でプロトコル操作を行います。ネットワーク I/O は Promise を返すため、呼び出し側は操作のステータスも確認してください。
6
-
7
- [API ナビゲーション](api.ja.md) · [基本概念](concepts.ja.md) · [ループバックのサンプル](../examples/network.cjs)
8
-
9
- 本番の Network は Node.js のトランスポートで SFML スタイルのインターフェースを実装します。FTP には basic-ftp、SFTP には ssh2、IPv6 の解析には ipaddr.js を使います。SFML C++ のネットワークモジュールは呼び出しません。Packet の形式と一部の値のセマンティクスは、独立した C++ プログラムと比較して検証しています。
10
-
11
- ## インターフェースと呼び出し方
12
-
13
- | インターフェース | 実装と適応 |
14
- |------|------------|
15
- | IpAddress | IPv4 の整数/4 バイトからの構築、IPv6 の 16 バイトからの構築、コピー、fromString、toString、toInteger、toBytes、getType、isV4/isV6。静的な resolve、getLocalAddress、getPublicAddress は Promise を返す |
16
- | Dns | resolve、queryNs、queryMx、querySrv、queryTxt、getPublicAddress。独立した Resolver とサーバー指定に対応 |
17
- | Socket | setBlocking、isBlocking、AnyPort、Status。getLastError は直近の下位層のエラーを返す |
18
- | TcpSocket | connect、disconnect、send、receive、ポート/リモートアドレスの照会。setupTlsClient、setupTlsServer、getCurrentCiphersuiteName |
19
- | TcpListener | listen、close、accept、getLocalPort |
20
- | UdpSocket | bind、unbind、send、receive、getLocalPort、MaxDatagramSize |
21
- | SocketSelector | add、remove、clear、wait、isReady、dispatchReadyCallbacks、コピーコンストラクター、assign。Receive/Send のビットフラグ |
22
- | Packet | append、clear、getData、getDataSize、getReadPosition、endOfPacket、isValid、コピーコンストラクター。型を明示する write/read。onSend/onReceive をオーバーライド可能 |
23
- | Http | setHost、sendRequest、Request、Response。HTTP リクエストのバージョンを明示的に指定 |
24
- | Ftp | connect、disconnect、login、keepAlive、作業ディレクトリ、ディレクトリ一覧、ディレクトリの移動/作成/削除、ファイルの名前変更/削除、アップロード/追記/ダウンロード、sendCommand |
25
- | Sftp | connect と login の分離、パスワード/鍵認証、getSessionInfo、パス解決、ディレクトリと属性、名前変更/削除、ストリーミングでのアップロードとダウンロード、TimeoutWithPredicate |
26
-
27
- I/O や待機を伴うメソッドは Promise を返し、純粋な状態照会や設定は同期的なままです。TcpSocket の `disconnect()`、listener.close、udp.unbind は、ローカルのトランスポートを同期的に終了します。FTP/SFTP の disconnect は Promise を返し、未完了の操作を中断する同期的な close も提供します。
28
-
29
- C++ の出力参照は、戻り値のオブジェクトで表現します。
30
-
31
- | 操作 | 戻り値 |
32
- |------|--------|
33
- | TCP send(Uint8Array) | `{ status, sent }` |
34
- | TCP receive(Uint8Array) | `{ status, received }` |
35
- | TCP send/receive(Packet) | `SocketStatus` |
36
- | UDP send(Uint8Array または Packet, address, port) | `SocketStatus` |
37
- | UDP receive(Uint8Array または Packet) | `{ status, received, remoteAddress?, remotePort }` |
38
-
39
- SocketHandle は Node の transport オブジェクトの型エイリアスで、protected の getNativeHandle だけに使います。プラットフォーム間で受け渡せる OS の fd/SOCKET の数値ではありません。
40
-
41
- ## TCP、UDP、Selector
42
-
43
- ```js
44
- const sf = require('sfml.js');
45
-
46
- function check(status) {
47
- if (status !== sf.SocketStatus.Done) {
48
- throw new Error(`Socket operation failed: ${status}`);
49
- }
50
- }
51
-
52
- async function exchange() {
53
- const listener = new sf.TcpListener();
54
- const client = new sf.TcpSocket();
55
- const peer = new sf.TcpSocket();
56
- try {
57
- check(await listener.listen(0, sf.IpAddress.LocalHost));
58
- const accepting = listener.accept(peer);
59
- check(await client.connect(sf.IpAddress.LocalHost,
60
- listener.getLocalPort(), sf.seconds(1)));
61
- check(await accepting);
62
-
63
- const received = new sf.Packet();
64
- const waiting = peer.receive(received);
65
- check(await client.send(
66
- new sf.Packet().write('string', '你好').write('u64', 42n)));
67
- check(await waiting);
68
- console.log(received.read('string'), received.read('u64'));
69
- } finally {
70
- listener.close();
71
- client.disconnect();
72
- peer.disconnect();
73
- }
74
- }
75
- exchange().catch(error => {
76
- console.error(error);
77
- process.exitCode = 1;
78
- });
79
- ```
80
-
81
- `setBlocking(true)` は、必要なデータや書き込み完了を Promise が待つことを意味し、イベントループをブロックしません。`setBlocking(false)` は、現在のラッパー層の状態に基づいて返すことを意味します。TCP connect は接続を開始して NotReady を返し、Selector.Send で接続準備の完了を待てます。TLS の初期化が HandshakeStarted を返した後は、同じ setup メソッドを繰り返し呼んでハンドシェイクの状態を取得できます。UDP の bind/send と TCP の listen は、実際のポートと操作結果を提供するため、引き続き Node の完了通知を待ちます。
82
-
83
- TCP の生バイト送信の sent は、今回ラッパー層が受け入れたバイト数です。ノンブロッキングモードでは、現在の Node writable highWaterMark の残り容量まで送信を受け付け、一部だけを受け入れた場合は Partial、空きがない場合は NotReady を返します。送信を続ける際は未送信の後半部分を渡してください。Node write が false を返すのはバックプレッシャーを示すだけで、今回すでにキューに入ったバイトを呼び出し側が再送する必要はありません。Done は、相手側のアプリケーションがデータを消費または永続化したことを意味しません。
84
-
85
- TCP Packet はビッグエンディアンの uint32 の長さ接頭辞を使います。Partial の後は同じ Packet を再度渡してください。ラッパー層は最初の送信のスナップショットとオフセットを保持します。その送信が完了するまでは、パケット内容の混在を防ぐため、他の送信は NotReady を返します。受信は、ヘッダーと本体が任意の位置で分割された場合に対応します。ノンブロッキングの NotReady は受信済みの部分を保持します。受信中の Packet が完了する前に、生バイトの受信へ切り替えることはできません。
86
-
87
- TCP の受信は Node readable のキューとバックプレッシャーを使い、無制限に増える別のデータコピーは作成しません。UDP はデータグラムの境界を維持します。転送先の配列がデータグラムより小さい場合は、そのデータグラムを破棄して Error を返します。UDP 受信キューの上限は 4096 データグラムまたは 8 MiB で、超えると新しいデータグラムを破棄します。1 データグラムの最大サイズは 65507 バイトです。TCP Packet の受信上限は 64 MiB で、超えると接続を閉じて Error を返します。
88
-
89
- Selector はラッパー層の読み取り/書き込み可能状態を監視するものであり、OS の生の select と同一であるとはしていません。1 回の wait が準備完了状態のスナップショットを保存し、isReady がそのスナップショットを照会し、dispatchReadyCallbacks が明示的にコールバックを配送します。wait がタイムアウトすると false を返します。メンバー集合の変更や全メンバーの終了で待機が解除されます。1 つの selector で同時に実行できる wait は 1 つだけで、変更後は再び wait できます。selector のコピーは、メンバー参照と準備完了スナップショットをコピーし、socket 自体はコピーしません。
90
-
91
- 接続を閉じると、保留中の読み取り、accept、Selector の待機が解除されます。新しい接続には新しい世代番号を使うため、古い操作が新しい接続のデータを読むことはありません。使用後はネットワークオブジェクトを明示的に閉じてください。有効な Node の接続はプロセスを存続させます。
92
-
93
- ## Packet
94
-
95
- 以降のコード内の `sf` は、すべて `require('sfml.js')` を指します。書き込みと読み取りでは、同じフィールド順序と型を使う必要があります。
96
-
97
- ```js
98
- const packet = new sf.Packet()
99
- .write('bool', true)
100
- .write('i32', -100)
101
- .write('u64', 18446744073709551615n)
102
- .write('f32', 1.5)
103
- .write('string', '音频🌟')
104
- .write('bytes', new Uint8Array([ 255, 0, 254 ]));
105
- ```
106
-
107
- | 型引数 | JS の型 | SFML のバイト形式 |
108
- |----------|---------|---------------|
109
- | bool | boolean | 1 バイト |
110
- | i8/u8、i16/u16、i32/u32 | number | 対応するビット幅の整数。ビッグエンディアン |
111
- | i64/u64 | bigint | 64 ビット整数。ビッグエンディアン |
112
- | f32/f64 | number | IEEE 浮動小数点。実行ホストのバイト順を使い、SFML の memcpy と一致 |
113
- | string | string | sf::String に対応。uint32 の文字数 + UTF-32 のビッグエンディアンのコードポイント |
114
- | utf8 | string | UTF-8 で std::string にエンコード。uint32 のバイト数 + バイト列 |
115
- | bytes | Uint8Array | バイナリの std::string。uint32 のバイト数 + 元のバイト列 |
116
-
117
- `read(type)` は対応する型を返します。データが不足すると undefined を返し、clear するまで isValid が false になります。失敗時に不足しているフィールドを飛ばすことはありません。文字列の長さだけが正常に読み取れた場合は、カーソルが文字列本体の先頭で止まります。整数の書き込みはビット幅に応じて変換し、64 ビット値は number を経由しません。エンディアンが異なるプラットフォーム間の浮動小数点 Packet は、元の SFML と同様に、双方で変換方法を取り決める必要があります。
118
-
119
- 内部では拡張可能な Buffer を使い、整数と浮動小数点の読み取りは同じメモリに直接アクセスします。getData は有効領域のビューを返し、空のパケットでは undefined を返します。このビューは読み取り専用として使ってください。容量拡張や clear の後も、古いビューは古い割り当てを維持します。append は入力をコピーし、送信は入力を受け入れた時点でスナップショットを作成します。呼び出し側がその後に入力を変更しても、送信済みのバイトは変わりません。追加の NAN マッピングや、バイトごとの言語境界を越える呼び出しはありません。
120
-
121
- onSend は送信するバイト列を返し、onReceive は完全なメッセージを受け取ります。サブクラスで圧縮や独自のエンコードを実装できます。ネットワーク受信は、onReceive を呼ぶ前に元のパケットを clear します。どちらのフックも同期的に実行されるため、非同期処理は send/receive の外で完了させてください。
122
-
123
- ## アドレス、DNS、TLS
124
-
125
- IpAddress は不変の値です。toBytes は独立した IPv6 バイト列のコピーを返し、toInteger は IPv4 にだけ適用できます。fromString は DNS を使わず、省略形の IPv4、8 進数形式、zone ID 付きの IPv6 は受け付けません。equal、notEqual、less、lessEqual、greater、greaterEqual はアドレスに対応します。並び順は最初に IPv4/IPv6、その後にバイト列で決まります。
126
-
127
- Dns.resolve はサーバーを指定しない場合、hosts ファイルを含むシステムの lookup を使います。この経路の完了時間はシステムのリゾルバーが制御します。サーバーを指定した場合は A/AAAA を並列に照会します。queryNs/Mx/Srv/Txt は独立した Resolver を使い、タイムアウト時にはその照会だけを取り消し、他の照会には影響しません。MX の priority は preference に、SRV の name は target にマッピングします。既定のサーバーへの照会が失敗した場合は undefined または空配列を返します。
128
-
129
- getLocalAddress は UDP のルート選択を通じてローカルアドレスを取得し、アプリケーションデータを送信しません。パブリックアドレスの照会には外部の DNS/HTTP サービスが必要です。オフラインテストでは実際のパブリックアドレス照会は行いません。Time.Zero はタイムアウトを設定しないことを意味します。
130
-
131
- TLS は接続済み TCP のクライアント側とサーバー側のアップグレードに対応します。クライアントは既定でシステム CA と hostname を検証します。証明書の文字列/バイト列を CA として渡すか、明示的に false を渡して検証を無効にできます。サーバーは証明書、秘密鍵、任意のパスフレーズを受け取ります。アップグレード前には plaintext の読み書きキューを空にする必要があります。証明書と暗号スイートは Node/OpenSSL が提供し、SFML の Mbed TLS と同じ集合であることは保証されません。
132
-
133
- ## HTTP
134
-
135
- ```javascript
136
- const sf = require('sfml.js');
137
-
138
- async function fetchText(host, uri) {
139
- const http = new sf.Http(host);
140
- const request = new sf.Http.Request(uri);
141
- const response = await http.sendRequest(request, sf.seconds(5));
142
- if (response.getStatus() !== sf.HttpStatus.Ok) {
143
- throw new Error(`HTTP status: ${response.getStatus()}`);
144
- }
145
- return response.getBody();
146
- }
147
- ```
148
-
149
- Request は setField、setMethod、setUri、setHttpVersion、setBody に対応します。Response はステータス、HTTP バージョン、フィールド、本文の照会に対応します。getBody は UTF-8 としてデコードし、getBodyBytes は独立した生バイト列を取得します。setBody は Uint8Array を直接受け取れます。
150
-
151
- SFML の HTTP/1.0/1.1 リクエスト行の明示的指定に対応するため、Node の TCP/TLS でリクエストを送信し、レスポンスを逐次解析します。解析は Content-Length、chunked、trailer、中間の 1xx、HEAD/本文のないステータス、接続終了による区切りに対応します。リクエスト本文には Content-Length を使い、矛盾する長さ指定と Transfer-Encoding を禁止します。リダイレクトの自動追跡、本文の展開、HTTP/2 へのアップグレードは行いません。
152
-
153
- sendRequest の Time はリクエスト全体を制限し、第 4 引数に AbortSignal を渡してキャンセルできます。不正または途中で途切れたレスポンスは InvalidResponse に、接続/TLS の失敗とキャンセルは ConnectionFailed にマッピングします。レスポンス本文の上限は 64 MiB、未完了のヘッダーまたは chunk framing の上限は 64 KiB です。setHost はアドレスを同期的に解析し、実際の DNS と接続は sendRequest 内で行います。
154
-
155
- ## FTP
156
-
157
- FTP は basic-ftp の制御接続、パッシブデータチャネル、ストリーミングファイル転送を使います。connect はログインせず、login の既定は anonymous です。列挙型とレスポンス型は、同梱の SFML ヘッダーから生成し、元の FTP ステータスコードはそのまま保持します。ディレクトリ一覧には NLST を送信します。
158
-
159
- download(remoteFile, localDirectory, mode) は、ローカルディレクトリ内にリモートのファイル名で書き込みます。upload(localFile, remoteDirectory, mode, append) は、リモートディレクトリ内にローカルのファイル名で書き込みます。Binary/Ascii/Ebcdic はそれぞれ TYPE I/A/E を送信し、モードへの対応はサーバーの応答によって決まります。renameFile、deleteDirectory などは対応する操作だけを行い、暗黙の再帰削除は行いません。sendCommand では他の FTP コマンドを送信でき、引数内の改行と NUL は拒否されます。
160
-
161
- 同じ Ftp オブジェクト上の操作は直列に実行します。connect の Time は接続確立だけを制限し、他のコマンドは close で明示的に中断できます。close は制御接続とデータ接続を閉じます。接続失敗、接続終了、ローカルファイルのエラーは対応する SFML レスポンスにマッピングし、サーバーエラーはステータスコードを保持します。
162
-
163
- <a id="sftp"></a>
164
- ## SFTP
165
-
166
- SFTP は ssh2 を使います。connect は SSH ネゴシエーションを完了し、認証の直前で止まります。getSessionInfo でホストの公開鍵、SHA-1/SHA-256 フィンガープリント、合意したアルゴリズムを取得できます。login はパスワード、または対応する公開鍵・秘密鍵とパスフレーズに対応し、認証に失敗しても再試行できます。
167
-
168
- ホスト鍵は known_hosts と自動照合しません。SFML と同様に、SessionInfo を公開して呼び出し側に判断を委ねます。サーバーの識別を検証する場合は、login の前に hostKey.sha256 を信頼済みのフィンガープリントと比較してください。
169
-
170
- 以下の関数には、アプリケーションから IpAddress、認証情報、既知の信頼済みフィンガープリント、データ消費コールバックを渡します。
171
-
172
- ```javascript
173
- async function download(address, username, password, trustedFingerprint, consume) {
174
- const client = new sf.Sftp();
175
- try {
176
- const connection = await client.connect(address, 22, sf.seconds(5));
177
- if (!connection.isOk()) throw new Error(connection.getMessage());
178
- const info = client.getSessionInfo();
179
- if (!info || info.hostKey.sha256 !== trustedFingerprint) {
180
- throw new Error('Unexpected SFTP host key');
181
- }
182
- const authentication = await client.login(username, password, sf.seconds(5));
183
- if (!authentication.isOk()) throw new Error(authentication.getMessage());
184
- const result = await client.download('/file', async bytes => {
185
- await consume(bytes);
186
- return true;
187
- });
188
- if (!result.isOk()) throw new Error(result.getMessage());
189
- } finally {
190
- client.close();
191
- }
192
- }
193
- ```
194
-
195
- download コールバックは最大 65536 バイトの Buffer ビューを受け取ります。false を返すと停止し、EOF はゼロバイトのコールバックで終了します。upload コールバックは `{ data, size }` を受け取り、Buffer に書き込んで size を有効なバイト数に設定します。false を返した場合も、今回の有効なデータを書き出してから停止します。コールバックは Promise を返せます。毎回独立した Buffer を割り当てるため、コールバックが古いビューを保持しても後続のブロックで上書きされることはありません。アップロードのコールバックが完了した後は、呼び出し側が送信済みのブロックを変更してはいけません。
196
-
197
- 属性にはパス、FileType、権限、bigint のサイズ/UID/GID、Date の時刻が含まれます。ssh2 のオフセットと属性の数値インターフェースは number を使うため、このバインディングは 0~2⁵³−1 の正確に表現できるオフセットだけを受け付けます。範囲外の値は拒否し、精度が黙って失われるのを防ぎます。時刻の精度はプロトコルが提供する秒単位です。rename(overwrite=true) は OpenSSH POSIX rename 拡張を使い、この拡張に対応しないサーバーはエラーを返します。
198
-
199
- Time は、1 回の進展のない待機に対する間隔へ変換されます。TimeoutWithPredicate は、接続に着信データも操作完了通知もない状態が 1 間隔に達すると述語を呼びます。true は待機を継続し、false は Timeout を返してセッションを閉じます。Time.Zero はタイマーを設定しません。これは Node のイベント層での待機であり、libssh2 の EAGAIN/カーネルの準備完了状態の詳細と同一視することはできません。
200
-
201
- close は進行中の待機を中断します。ユーザーコールバックの Promise を強制終了することはできませんが、後から完了しても、再接続されたセッションで読み書きを続けることはありません。SFTP プロトコルのステータスは対応する Result.Value にマッピングします。下位層のエラーを libssh2 固有の値と一対一で対応付けられない場合は、固有のエラーを作り出すのではなく、Error と元のメッセージを返します。
202
-
203
- ## 検証とデモ
204
-
205
- `npm run demo:network` はローカルのループバックアドレスで TCP、Packet、UDP、Selector のサンプルを実行し、終了時にすべての接続を閉じます。
206
-
207
- `npm run test:runtime` にはネットワークテストが含まれます。ローカルの TCP/UDP/DNS/FTP/SSH サービスを起動し、実際のソケット、分割されたメッセージ、送信時のバックプレッシャー、TLS の信頼と hostname の失敗、パスワードと公開鍵の認証、ディレクトリとストリーミングファイル操作、タイムアウト、キャンセルをテストします。`network-oracle.test.cjs` は一時ディレクトリで SFML C++ プログラムをコンパイルし、Packet の各フィールドのバイト列と IPv4/IPv6 文字列を比較します。Windows ではこの Unix 向けコンパイルコマンドをスキップします。
208
-
209
- 依存関係のバージョンは [package.json](../package.json) とロックファイルを基準とします。ローカルのループバックテストは公開サービスの可用性を検証しません。プラットフォームの設定と実行方法は[開発ガイド](development.ja.md#testing)を参照してください。
210
-
211
- <a id="sfml-cpp-reference"></a>
212
- ## SFML C++ リファレンス
213
-
214
- 上流の [Packet](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Packet.html)、[TcpSocket](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1TcpSocket.html)、[UdpSocket](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1UdpSocket.html)、[Http](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Http.html)、[Ftp](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Ftp.html)、[Sftp](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Sftp.html) は、パケット形式とプロトコルの概念を確認するための資料です。実際の通信には Node.js のトランスポートと Promise ベースの I/O を使うため、ステータス、サイズ上限、待機の挙動は、この JavaScript 向けガイドの説明を優先してください。