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.
- package/README.ja.md +10 -9
- package/README.ko.md +10 -9
- package/README.md +10 -9
- package/README.zh-CN.md +10 -9
- package/binding.gyp +23 -16
- package/dist/audio/effect-processor.js +9 -3
- package/dist/audio/input-sound-file.js +41 -15
- package/dist/audio/listener.js +33 -11
- package/dist/audio/music.js +41 -18
- package/dist/audio/output-sound-file.js +4 -2
- package/dist/audio/playback-device.js +11 -3
- package/dist/audio/sound-buffer-recorder.js +8 -5
- package/dist/audio/sound-buffer.js +40 -17
- package/dist/audio/sound-file-factory.js +21 -9
- package/dist/audio/sound-file-reader.js +21 -7
- package/dist/audio/sound-recorder.js +36 -15
- package/dist/audio/sound-source.js +117 -40
- package/dist/audio/sound-stream.js +14 -5
- package/dist/audio/sound.js +9 -4
- package/dist/audio/value.js +42 -16
- package/dist/graphics/blend-mode.js +2 -1
- package/dist/graphics/boolean-vector.d.ts +1 -2
- package/dist/graphics/boolean-vector.js +19 -9
- package/dist/graphics/color.js +2 -1
- package/dist/graphics/convex-shape.js +7 -3
- package/dist/graphics/font.js +52 -23
- package/dist/graphics/glsl-matrix.js +8 -3
- package/dist/graphics/glsl.js +47 -16
- package/dist/graphics/glyph.js +27 -10
- package/dist/graphics/image.js +30 -14
- package/dist/graphics/rect.js +15 -8
- package/dist/graphics/render-states.js +18 -9
- package/dist/graphics/render-target.js +49 -23
- package/dist/graphics/render-texture.js +24 -12
- package/dist/graphics/render-window.js +6 -3
- package/dist/graphics/shader.js +67 -32
- package/dist/graphics/shape.js +25 -13
- package/dist/graphics/sprite.js +19 -9
- package/dist/graphics/stencil-mode.js +10 -6
- package/dist/graphics/swap.js +2 -1
- package/dist/graphics/text.js +123 -48
- package/dist/graphics/texture.js +48 -24
- package/dist/graphics/transform.js +29 -13
- package/dist/graphics/transformable.js +2 -1
- package/dist/graphics/vertex-array.js +40 -18
- package/dist/graphics/vertex-buffer.js +39 -19
- package/dist/graphics/vertex.js +6 -3
- package/dist/graphics/view.js +30 -14
- package/dist/index.d.ts +4 -4
- package/dist/internal/audio-codec-registry.js +12 -6
- package/dist/internal/audio-input-stream.js +2 -1
- package/dist/internal/audio-music-pump.js +58 -24
- package/dist/internal/audio-recorder-session.js +17 -7
- package/dist/internal/audio-worker-session.js +28 -10
- package/dist/internal/audio-worker.js +40 -21
- package/dist/internal/glsl-value.d.ts +3 -1
- package/dist/internal/glsl-value.js +18 -8
- package/dist/internal/graphics-state.js +29 -15
- package/dist/internal/input-stream.d.ts +3 -1
- package/dist/internal/input-stream.js +16 -7
- package/dist/internal/numeric-properties.js +2 -1
- package/dist/internal/render-states.js +2 -1
- package/dist/internal/scalar.js +22 -13
- package/dist/internal/shaped-glyph.d.ts +3 -1
- package/dist/internal/shaped-glyph.js +12 -4
- package/dist/internal/struct-view.d.ts +3 -1
- package/dist/internal/struct-view.js +3 -1
- package/dist/internal/transformable.js +2 -1
- package/dist/network/common.js +23 -11
- package/dist/network/dns.js +25 -17
- package/dist/network/ftp.js +43 -18
- package/dist/network/http.js +126 -56
- package/dist/network/ip-address.js +50 -25
- package/dist/network/packet.js +63 -25
- package/dist/network/sftp.js +175 -74
- package/dist/network/socket-selector.js +28 -14
- package/dist/network/socket.js +71 -30
- package/dist/network/tcp-listener.js +42 -19
- package/dist/network/tcp-socket.js +111 -53
- package/dist/network/tls-material.js +2 -1
- package/dist/network/udp-socket.js +68 -33
- package/dist/system/angle.js +2 -1
- package/dist/system/clock.js +4 -2
- package/dist/system/err.js +5 -2
- package/dist/system/file-input-stream.js +8 -4
- package/dist/system/input-stream.js +6 -3
- package/dist/system/operators.d.ts +1 -1
- package/dist/system/operators.js +90 -50
- package/dist/system/sleep.js +4 -2
- package/dist/system/time.js +12 -6
- package/dist/system/vector2.js +6 -7
- package/dist/system/vector3.js +11 -6
- package/dist/window/clipboard.js +2 -1
- package/dist/window/context.js +10 -5
- package/dist/window/cursor.js +2 -1
- package/dist/window/event.js +9 -5
- package/dist/window/mouse.js +4 -2
- package/dist/window/video-mode.js +2 -1
- package/dist/window/window.js +19 -12
- package/native/addon.cc +25 -12
- package/native/audio-binding.cc +266 -126
- package/native/audio-codec-binding.cc +147 -77
- package/native/audio-device-binding.cc +76 -49
- package/native/audio-file-binding.cc +116 -67
- package/native/audio-recorder-binding.cc +147 -98
- package/native/audio-recorder.h +1 -1
- package/native/audio-state.h +53 -30
- package/native/audio-stream-binding.cc +148 -94
- package/native/audio-stream.h +5 -4
- package/native/audio-worker-binding.cc +163 -81
- package/native/audio-worker.h +35 -19
- package/native/batch-drawable.cc +29 -16
- package/native/batch-drawable.h +11 -8
- package/native/context-binding.cc +40 -27
- package/native/context-settings.h +15 -8
- package/native/deferred-delete.cc +9 -6
- package/native/deferred-delete.h +7 -8
- package/native/error-stream-binding.cc +42 -28
- package/native/font-binding.cc +89 -48
- package/native/graphics-binding.cc +122 -72
- package/native/graphics-state.h +50 -36
- package/native/image-binding.cc +38 -24
- package/native/image-state.h +26 -18
- package/native/input-binding.cc +42 -27
- package/native/render-window-binding.cc +38 -23
- package/native/shader-binding.cc +115 -50
- package/native/shape-binding.cc +94 -49
- package/native/shape-state.h +18 -9
- package/native/shaped-glyph-storage.h +9 -5
- package/native/stream-binding.cc +143 -117
- package/native/system-binding.cc +17 -12
- package/native/text-binding.cc +68 -35
- package/native/text-state.h +25 -18
- package/native/texture-binding.cc +42 -33
- package/native/texture-resource.h +20 -12
- package/native/time-value.h +3 -1
- package/native/transformable-binding.cc +12 -6
- package/native/transformable-state.h +6 -6
- package/native/value-binding.h +46 -28
- package/native/value-layout.h +10 -10
- package/native/values-binding.cc +29 -23
- package/native/vertex-binding.cc +18 -12
- package/native/vertex-buffer-binding.cc +38 -24
- package/native/vertex-storage.h +2 -2
- package/native/view-data.h +4 -3
- package/native/window-binding.cc +75 -45
- package/native/window-event.h +20 -11
- package/native/window-owner.h +15 -12
- package/package.json +40 -48
- package/src/audio/effect-processor.ts +9 -3
- package/src/audio/input-sound-file.ts +108 -36
- package/src/audio/listener.ts +39 -13
- package/src/audio/music.ts +112 -47
- package/src/audio/output-sound-file.ts +40 -11
- package/src/audio/playback-device.ts +23 -8
- package/src/audio/sound-buffer-recorder.ts +35 -13
- package/src/audio/sound-buffer.ts +166 -58
- package/src/audio/sound-file-factory.ts +127 -49
- package/src/audio/sound-file-reader.ts +49 -15
- package/src/audio/sound-recorder.ts +100 -34
- package/src/audio/sound-source.ts +142 -45
- package/src/audio/sound-stream.ts +15 -5
- package/src/audio/sound.ts +12 -4
- package/src/audio/value.ts +89 -26
- package/src/graphics/blend-mode.ts +3 -1
- package/src/graphics/boolean-vector.ts +56 -26
- package/src/graphics/color.ts +3 -1
- package/src/graphics/convex-shape.ts +10 -3
- package/src/graphics/font.ts +171 -50
- package/src/graphics/glsl-matrix.ts +9 -3
- package/src/graphics/glsl.ts +81 -35
- package/src/graphics/glyph.ts +67 -26
- package/src/graphics/image.ts +119 -45
- package/src/graphics/rect.ts +56 -24
- package/src/graphics/render-states.ts +31 -14
- package/src/graphics/render-target.ts +197 -81
- package/src/graphics/render-texture.ts +36 -12
- package/src/graphics/render-window.ts +9 -3
- package/src/graphics/shader.ts +186 -61
- package/src/graphics/shape.ts +93 -35
- package/src/graphics/sprite.ts +64 -25
- package/src/graphics/stencil-mode.ts +12 -6
- package/src/graphics/swap.ts +3 -2
- package/src/graphics/text.ts +229 -74
- package/src/graphics/texture.ts +180 -61
- package/src/graphics/transform.ts +132 -47
- package/src/graphics/transformable.ts +3 -1
- package/src/graphics/vertex-array.ts +87 -35
- package/src/graphics/vertex-buffer.ts +97 -33
- package/src/graphics/vertex.ts +9 -3
- package/src/graphics/view.ts +59 -21
- package/src/index.ts +101 -23
- package/src/internal/audio-codec-registry.ts +18 -6
- package/src/internal/audio-input-stream.ts +6 -2
- package/src/internal/audio-music-pump.ts +116 -41
- package/src/internal/audio-native.ts +249 -96
- package/src/internal/audio-recorder-session.ts +68 -24
- package/src/internal/audio-worker-session.ts +65 -21
- package/src/internal/audio-worker.ts +85 -41
- package/src/internal/glsl-value.ts +26 -11
- package/src/internal/graphics-state.ts +57 -20
- package/src/internal/input-stream.ts +23 -10
- package/src/internal/native.ts +252 -99
- package/src/internal/numeric-properties.ts +2 -1
- package/src/internal/render-states.ts +3 -1
- package/src/internal/scalar.ts +33 -14
- package/src/internal/shaped-glyph.ts +25 -12
- package/src/internal/struct-view.ts +40 -13
- package/src/internal/transformable.ts +3 -1
- package/src/network/common.ts +35 -11
- package/src/network/dns.ts +95 -38
- package/src/network/ftp.ts +129 -47
- package/src/network/http.ts +232 -77
- package/src/network/ip-address.ts +118 -48
- package/src/network/packet.ts +161 -54
- package/src/network/sftp.ts +498 -168
- package/src/network/socket-selector.ts +66 -26
- package/src/network/socket.ts +133 -46
- package/src/network/tcp-listener.ts +78 -29
- package/src/network/tcp-socket.ts +240 -95
- package/src/network/tls-material.ts +6 -2
- package/src/network/udp-socket.ts +147 -53
- package/src/system/angle.ts +3 -1
- package/src/system/clock.ts +12 -4
- package/src/system/err.ts +5 -2
- package/src/system/file-input-stream.ts +12 -4
- package/src/system/input-stream.ts +9 -3
- package/src/system/operators.ts +290 -115
- package/src/system/sleep.ts +6 -2
- package/src/system/time.ts +18 -6
- package/src/system/timeout-with-predicate.ts +19 -8
- package/src/system/vector2.ts +101 -49
- package/src/system/vector3.ts +85 -36
- package/src/window/clipboard.ts +3 -1
- package/src/window/context.ts +15 -5
- package/src/window/cursor.ts +3 -1
- package/src/window/event.ts +26 -12
- package/src/window/mouse.ts +6 -2
- package/src/window/video-mode.ts +3 -1
- package/src/window/window.ts +119 -37
- package/test/native/audio-probes.cc +74 -36
- package/test/native/deferred-delete-probes.cc +17 -11
- package/test/native/drawable-probes.cc +70 -36
- package/test/native/exception-probes.cc +14 -9
- package/test/native/image-probes.cc +20 -10
- package/test/native/matrix-probes.cc +8 -4
- package/test/native/network-oracle.cc +17 -11
- package/test/native/render-texture-probes.cc +33 -24
- package/test/native/shader-probes.cc +9 -9
- package/test/native/shape-probes.cc +37 -23
- package/test/native/sprite-probes.cc +41 -25
- package/test/native/system-probes.cc +58 -35
- package/test/native/text-probes.cc +77 -44
- package/test/native/texture-probes.cc +43 -26
- package/test/native/time-probes.cc +18 -12
- package/test/native/transform-probes.cc +15 -10
- package/test/native/transformable-probes.cc +23 -17
- package/test/native/value-oracle.h +9 -4
- package/test/native/value-probes.cc +31 -23
- package/test/native/vertex-array-probes.cc +22 -14
- package/test/native/vertex-buffer-probes.cc +28 -17
- package/test/native/view-probes.cc +29 -17
- package/test/native/window-probes.cc +66 -33
- package/tools/ensure-sfml.cjs +9 -0
- package/tools/generate-network-constants.cjs +11 -6
- package/tools/generate-window-constants.cjs +31 -12
- package/docs/README.ja.md +0 -30
- package/docs/README.ko.md +0 -30
- package/docs/README.md +0 -30
- package/docs/README.zh-CN.md +0 -30
- package/docs/api.ja.md +0 -84
- package/docs/api.ko.md +0 -84
- package/docs/api.md +0 -81
- package/docs/api.zh-CN.md +0 -81
- package/docs/audio.ja.md +0 -249
- package/docs/audio.ko.md +0 -251
- package/docs/audio.md +0 -252
- package/docs/audio.zh-CN.md +0 -252
- package/docs/concepts.ja.md +0 -130
- package/docs/concepts.ko.md +0 -130
- package/docs/concepts.md +0 -131
- package/docs/concepts.zh-CN.md +0 -131
- package/docs/development.ja.md +0 -144
- package/docs/development.ko.md +0 -144
- package/docs/development.md +0 -146
- package/docs/development.zh-CN.md +0 -146
- package/docs/getting-started.ja.md +0 -154
- package/docs/getting-started.ko.md +0 -154
- package/docs/getting-started.md +0 -156
- package/docs/getting-started.zh-CN.md +0 -156
- package/docs/graphics.ja.md +0 -256
- package/docs/graphics.ko.md +0 -254
- package/docs/graphics.md +0 -255
- package/docs/graphics.zh-CN.md +0 -257
- package/docs/network.ja.md +0 -214
- package/docs/network.ko.md +0 -216
- package/docs/network.md +0 -218
- package/docs/network.zh-CN.md +0 -218
- package/docs/system.ja.md +0 -169
- package/docs/system.ko.md +0 -171
- package/docs/system.md +0 -173
- package/docs/system.zh-CN.md +0 -173
- package/docs/window.ja.md +0 -138
- package/docs/window.ko.md +0 -140
- package/docs/window.md +0 -141
- package/docs/window.zh-CN.md +0 -141
- package/native/exception-boundary.h +0 -97
- package/native/numeric-fields.h +0 -96
- package/native/shared-handle.h +0 -107
- package/test/tsconfig.json +0 -8
- package/tools/configure-lsp.cjs +0 -23
- package/tools/lib_downloader.cjs +0 -92
- package/tools/lib_downloader_urls.cjs +0 -23
package/docs/network.zh-CN.md
DELETED
|
@@ -1,218 +0,0 @@
|
|
|
1
|
-
# Network
|
|
2
|
-
|
|
3
|
-
[English](network.md) · **简体中文** · [日本語](network.ja.md) · [한국어](network.ko.md)
|
|
4
|
-
|
|
5
|
-
> 使用 Packet 定义报文,通过 TCP/UDP 传输,或使用 HTTP、FTP、SFTP 完成协议操作。网络 I/O 返回 Promise,调用方同时检查操作状态。
|
|
6
|
-
|
|
7
|
-
[API 导航](api.zh-CN.md) · [核心概念](concepts.zh-CN.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 整数/四字节构造,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,纯状态查询和配置仍同步。`disconnect()` 的 TcpSocket 版本、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 对象的类型别名,仅用于受保护的 getNativeHandle;它不是可跨平台传递的操作系统 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,超过后丢弃新报文。单报文最大 65507 字节。TCP Packet 接收限制为 64 MiB;超限关闭连接并返回 Error。
|
|
88
|
-
|
|
89
|
-
Selector 观察封装层可读/可写状态,不声称等同于原始系统 select。一次 wait 保存就绪快照,isReady 查询该快照,dispatchReadyCallbacks 显式派发;wait 超时返回 false。修改成员集合或关闭全部成员会唤醒等待。一个 selector 同时只允许一个 wait;修改后可再次 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 | 一个字节 |
|
|
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,并使 isValid 为 false,直到 clear。失败不会跳过缺失字段;字符串长度已成功读取时,游标停在字符串正文开头。整数写入按位宽转换,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、八进制形式或带 zone ID 的 IPv6。equal、notEqual、less、lessEqual、greater、greaterEqual 支持地址;排序先按 IPv4/IPv6,再按字节。
|
|
126
|
-
|
|
127
|
-
Dns.resolve 在不指定服务器时使用系统 lookup,包括 hosts 文件;这条路径的完成时间由系统解析器控制。指定服务器时并行查 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 限制整次请求,可传第四个 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
|
-
|
|
165
|
-
## SFTP
|
|
166
|
-
|
|
167
|
-
SFTP 使用 ssh2。connect 完成 SSH 协商并停在认证前,getSessionInfo 可读取主机公钥、SHA-1/SHA-256 指纹以及协商算法;login 支持密码或匹配的公私钥和口令,认证失败可重试。
|
|
168
|
-
|
|
169
|
-
主机密钥不自动匹配 known_hosts,沿用 SFML 暴露 SessionInfo 供调用方判断的方式。需要校验服务器身份时,在 login 前将 hostKey.sha256 与可信指纹比较。
|
|
170
|
-
|
|
171
|
-
下面的函数由应用传入 IpAddress、认证信息、已知可信指纹和消费回调:
|
|
172
|
-
|
|
173
|
-
```javascript
|
|
174
|
-
async function download(address, username, password, trustedFingerprint, consume) {
|
|
175
|
-
const client = new sf.Sftp();
|
|
176
|
-
try {
|
|
177
|
-
const connection = await client.connect(address, 22, sf.seconds(5));
|
|
178
|
-
if (!connection.isOk()) throw new Error(connection.getMessage());
|
|
179
|
-
const info = client.getSessionInfo();
|
|
180
|
-
if (!info || info.hostKey.sha256 !== trustedFingerprint) {
|
|
181
|
-
throw new Error('Unexpected SFTP host key');
|
|
182
|
-
}
|
|
183
|
-
const authentication = await client.login(username, password, sf.seconds(5));
|
|
184
|
-
if (!authentication.isOk()) throw new Error(authentication.getMessage());
|
|
185
|
-
const result = await client.download('/file', async bytes => {
|
|
186
|
-
await consume(bytes);
|
|
187
|
-
return true;
|
|
188
|
-
});
|
|
189
|
-
if (!result.isOk()) throw new Error(result.getMessage());
|
|
190
|
-
} finally {
|
|
191
|
-
client.close();
|
|
192
|
-
}
|
|
193
|
-
}
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
download 回调接收最多 65536 字节的 Buffer 视图;返回 false 停止,EOF 会以零字节回调结束。upload 回调接收 `{ data, size }`,填写 Buffer,将 size 设为有效字节数,返回 false 时仍写出本次有效数据后停止。回调可以返回 Promise。每次分配独立 Buffer,回调保留旧视图不会看到后续块覆盖;上传回调完成后,调用方不得继续修改已提交块。
|
|
197
|
-
|
|
198
|
-
属性包含路径、FileType、权限、bigint 大小/UID/GID,以及 Date 时间。ssh2 的偏移和属性数值接口使用 number,因此本绑定只接受 0~2⁵³−1 的精确偏移,超过范围拒绝,避免静默丢失精度;时间精度为协议提供的秒。rename(overwrite=true) 使用 OpenSSH POSIX rename 扩展,不支持该扩展的服务器返回错误。
|
|
199
|
-
|
|
200
|
-
Time 转为单次无进展等待的周期;TimeoutWithPredicate 在连接没有入站数据或操作完成通知达到一个周期时调用谓词,true 继续等待,false 返回 Timeout 并关闭会话。Time.Zero 不设置计时器。该机制是 Node 事件层面的等待,不能等同于 libssh2 的 EAGAIN/内核就绪细节。
|
|
201
|
-
|
|
202
|
-
close 会中断进行中的等待;用户回调 Promise 无法被强行终止,但它随后完成时不会对重新建立的会话继续读写。SFTP 协议状态映射为对应 Result.Value;底层错误无法与 libssh2 专属值逐一对应时返回 Error 和原消息,不伪造专属错误。
|
|
203
|
-
|
|
204
|
-
## 验证与演示
|
|
205
|
-
|
|
206
|
-
`npm run demo:network` 在本机回环地址运行 TCP、Packet、UDP、Selector 示例,结束时关闭所有连接。
|
|
207
|
-
|
|
208
|
-
`npm run test:runtime` 包含网络测试,启动本地 TCP/UDP/DNS/FTP/SSH 服务,测试真实套接字、分段报文、发送背压、TLS 信任与 hostname 失败、密码和公钥认证、目录与流式文件操作、超时和取消。`network-oracle.test.cjs` 在临时目录编译 SFML C++ 程序,对照 Packet 每个字段的字节与 IPv4/IPv6 字符串;Windows 下跳过该 Unix 编译命令。
|
|
209
|
-
|
|
210
|
-
依赖版本以 [package.json](../package.json) 和锁文件为准。本地回环测试不验证公网服务可用性;平台配置与执行方法见 [开发指南](development.zh-CN.md#testing)。
|
|
211
|
-
|
|
212
|
-
<a id="sfml-cpp-reference"></a>
|
|
213
|
-
|
|
214
|
-
## SFML C++ 参考
|
|
215
|
-
|
|
216
|
-
报文与套接字参考 [sf::Packet](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Packet.html)、[sf::TcpSocket](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1TcpSocket.html)、[sf::UdpSocket](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1UdpSocket.html);应用协议参考 [sf::Http](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Http.html)、[sf::Ftp](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Ftp.html)、[sf::Sftp](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Sftp.html)。
|
|
217
|
-
|
|
218
|
-
上游文档可用于理解 Packet 格式与协议概念。实际传输由 Node.js 实现,Promise I/O、状态返回、背压、超时和容量限制以本文为准;不要假设与 C++ 的阻塞调用或系统句柄完全相同。
|
package/docs/system.ja.md
DELETED
|
@@ -1,169 +0,0 @@
|
|
|
1
|
-
# System
|
|
2
|
-
|
|
3
|
-
[English](system.md) / [简体中文](system.zh-CN.md) / **日本語** / [한국어](system.ko.md)
|
|
4
|
-
|
|
5
|
-
> System は値型、時間、入力ストリーム、Unicode の境界判定、エラー処理を提供します。通常の数値計算は JS で行い、リソースに関わる操作はインターフェースに応じてネイティブ側で実行します。
|
|
6
|
-
|
|
7
|
-
[API ナビゲーション](api.ja.md) · [基本概念](concepts.ja.md)
|
|
8
|
-
|
|
9
|
-
## ベクトルと演算
|
|
10
|
-
|
|
11
|
-
```typescript
|
|
12
|
-
import { Vector2f, Vector2i, add, multiply, addAssign } from 'sfml.js';
|
|
13
|
-
|
|
14
|
-
const position = new Vector2f(10, 20);
|
|
15
|
-
const velocity = new Vector2f(2, 3);
|
|
16
|
-
const next = add(position, velocity);
|
|
17
|
-
const doubled = multiply(velocity, 2);
|
|
18
|
-
addAssign(position, velocity);
|
|
19
|
-
const pixels = new Vector2i(position);
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
通常の演算は独立した値を返し、`*Assign` は左オペランドを変更してそれを返します。代入でベクトルのスカラー型が自動変換されることはありません。変換が必要な場合は対応するコンストラクターを使います。
|
|
23
|
-
|
|
24
|
-
| スカラータグ | JS の成分型 | ストレージ |
|
|
25
|
-
| --- | --- | --- |
|
|
26
|
-
| `i8`/`u8` | number | Int8Array/Uint8Array |
|
|
27
|
-
| `i16`/`u16` | number | Int16Array/Uint16Array |
|
|
28
|
-
| `i32`/`u32` | number | Int32Array/Uint32Array |
|
|
29
|
-
| `i64`/`u64` | bigint | BigInt64Array/BigUint64Array |
|
|
30
|
-
| `f32`/`f64` | number | Float32Array/Float64Array |
|
|
31
|
-
|
|
32
|
-
`Vector2i/u/f` と `Vector3i/u/f` はそれぞれ i32/u32/f32 に対応します。他のスカラー型には `new Vector2('f64', x, y)` などの形式を使います。
|
|
33
|
-
|
|
34
|
-
両方のベクトル型は `lengthSquared()`、`dot()`、`cross()`、成分ごとの乗除算を提供し、2 次元ベクトルはさらに `perpendicular()` を提供します。浮動小数点ベクトルは `length()` と `normalized()` を提供し、浮動小数点の 2 次元ベクトルは角度、回転、射影の操作も提供します。整数ベクトルでは、浮動小数点型専用のメソッドは使えません。
|
|
35
|
-
|
|
36
|
-
ベクトルの `multiply()`/`divide()` はスカラーを使います。成分ごとの操作には `componentWiseMul()`/`componentWiseDiv()` を使います。ゼロ除算、ゼロベクトルの正規化、ゼロ軸への射影は例外を投げます。64 ビット整数の計算では bigint を維持し、f32 の計算は SFML の精度規則に従って丸めます。三角関数の計算では、プラットフォームの数学ライブラリによる限定的な差異を許容します。
|
|
37
|
-
|
|
38
|
-
## 角度
|
|
39
|
-
|
|
40
|
-
```typescript
|
|
41
|
-
import { Angle, degrees, radians, divide } from 'sfml.js';
|
|
42
|
-
|
|
43
|
-
const heading = degrees(90);
|
|
44
|
-
const turn = radians(Math.PI);
|
|
45
|
-
const copy = new Angle(heading);
|
|
46
|
-
const ratio = divide(turn, heading);
|
|
47
|
-
console.log(copy.asDegrees(), ratio);
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
回転のインターフェースは Angle を受け取ります。`wrapSigned()`、`wrapUnsigned()` はそれぞれの範囲に折り返した角度を返しますが、比較時には自動的に折り返しません。`Angle.Zero` は読み取り専用の定数で、コピーすれば変更できます。Angle は float32 を使い、剰余演算では正の除数が必要です。
|
|
51
|
-
|
|
52
|
-
## 時間とクロック
|
|
53
|
-
|
|
54
|
-
```typescript
|
|
55
|
-
import { Clock, milliseconds, microseconds, sleep } from 'sfml.js';
|
|
56
|
-
|
|
57
|
-
const clock = new Clock();
|
|
58
|
-
await sleep(milliseconds(16));
|
|
59
|
-
const elapsed = clock.restart();
|
|
60
|
-
console.log(elapsed.asSeconds(), elapsed.asMicroseconds());
|
|
61
|
-
console.log(microseconds(1000n).asMilliseconds());
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
| インターフェース | セマンティクス |
|
|
65
|
-
| --- | --- |
|
|
66
|
-
| `new Time()`/`new Time(source)`/`new Time(bigint)` | 長さゼロ、コピー、マイクロ秒指定で構築 |
|
|
67
|
-
| `seconds(number)` | 秒を Time に変換 |
|
|
68
|
-
| `milliseconds(number)` | int32 のミリ秒入力。小数部はゼロ方向に切り捨て |
|
|
69
|
-
| `microseconds(bigint)` | マイクロ秒入力 |
|
|
70
|
-
| `asMicroseconds()`/`toDuration()` | マイクロ秒の bigint |
|
|
71
|
-
| `asSeconds()`/`asMilliseconds()` | float32 の秒/int32 のミリ秒 |
|
|
72
|
-
| `Clock.start()`/`stop()` | 計測の再開/一時停止 |
|
|
73
|
-
| `Clock.restart()`/`reset()` | それまでの経過時間を返し、ゼロに戻して実行/停止 |
|
|
74
|
-
|
|
75
|
-
Time は符号付き int64 のマイクロ秒を保持し、整数倍の演算には bigint、浮動小数点の倍率には number を使います。`Time.Zero` は読み取り専用の定数です。範囲外の値や不正な除算は RangeError を投げ、インプレース演算が失敗した場合は元の値を保持します。
|
|
76
|
-
|
|
77
|
-
Clock は `process.hrtime.bigint()` を使い、独立した Time のスナップショットを返します。独自のタイマーは持たず、クロックの分解能とシステムのスリープ時の挙動は Node.js とプラットフォームによって決まります。
|
|
78
|
-
|
|
79
|
-
`sleep(time)` は Promise を返し、Node のタイマーで待機するため、イベントループをブロックしません。正の時間はミリ秒単位に切り上げ、ゼロと負の時間は直ちに完了します。実際の再開時刻はスケジューリングの影響を受けます。
|
|
80
|
-
|
|
81
|
-
### タイムアウトの設定
|
|
82
|
-
|
|
83
|
-
`TimeoutWithPredicate` は確認間隔と述語を保持するだけで、自身ではタイマーを開始しません。
|
|
84
|
-
|
|
85
|
-
- `new TimeoutWithPredicate(time)`:固定間隔で、述語は常に false を返します。
|
|
86
|
-
- `new TimeoutWithPredicate(predicate, period?)`:既定の間隔は 1 ms で、true は待機を続けることを意味します。
|
|
87
|
-
- `getPeriod()` は読み取り専用の Time を、`getPredicate()` は元の関数を返します。
|
|
88
|
-
|
|
89
|
-
確認のタイミングは、これを受け取るインターフェースが決定します。現在は SFTP が進展のない待機を制御するために使っています。詳細は [Network](network.ja.md#sftp) を参照してください。
|
|
90
|
-
|
|
91
|
-
`SuspendAwareClock.now()` は、システムのスリープ時間を含むネイティブのナノ秒単位の時刻を返します。Android 分岐のみでサポートされ、デスクトップでの呼び出しは SFMLError を投げます。現在の自動ダウンロードフローには Android のビルド対象はありません。
|
|
92
|
-
|
|
93
|
-
## 色、矩形、頂点
|
|
94
|
-
|
|
95
|
-
| 型 | 構築と主な操作 |
|
|
96
|
-
| --- | --- |
|
|
97
|
-
| Color | RGB/RGBA、`0xRRGGBBAA`、コピー。`r/g/b/a`、`toInteger()` |
|
|
98
|
-
| FloatRect/IntRect | `position` + `size`、コピー、明示的変換。`contains()`、`findIntersection()`、`getCenter()` |
|
|
99
|
-
| Vertex | `position`、`color`、`texCoords`、またはコピーコンストラクター |
|
|
100
|
-
|
|
101
|
-
これらの値は主にグラフィックスのインターフェースで使います。Color の成分は uint8 で保存され、直接書き込むとその幅に縮小されます。色の加減算は飽和演算であり、色同士の乗算はチャンネルごとに `floor(a * b / 255)` を計算します。Color の定数は読み取り専用です。
|
|
102
|
-
|
|
103
|
-
矩形と頂点のメンバーは共有ビューです。矩形には左端と上端を含み、右端と下端は含みません。負のサイズは正規化した範囲として計算し、交差部分の面積が正でなければ `undefined` を返します。Vertex の既定の位置とテクスチャ座標はゼロ、色は白です。
|
|
104
|
-
|
|
105
|
-
<a id="input-streams"></a>
|
|
106
|
-
## 入力ストリーム
|
|
107
|
-
|
|
108
|
-
InputStream はシーク可能なバイトストリームのプロトコルです。メソッドは同期値または Promise を返せます。
|
|
109
|
-
|
|
110
|
-
| メソッド | 戻り値 |
|
|
111
|
-
| --- | --- |
|
|
112
|
-
| `read(data)` | Uint8Array に書き込み、実際のバイト数を bigint で返す。EOF は `0n` |
|
|
113
|
-
| `seek(position)` | 実際のバイト位置を bigint で返す |
|
|
114
|
-
| `tell()` | 現在のバイト位置の bigint |
|
|
115
|
-
| `getSize()` | 総バイト数の bigint |
|
|
116
|
-
|
|
117
|
-
`undefined` は I/O の失敗を意味し、投げられたエラーはそのまま伝播します。これら 4 つのメソッドを実装したオブジェクトもストリームとして渡せます。Node Readable には、シーク機能を補うアダプターが必要です。
|
|
118
|
-
|
|
119
|
-
`MemoryInputStream(data)` は入力バイト列への参照を保持します。読み込み中は内容を変更せず、1 回の操作がカーソルを専有するようにしてください。`FileInputStream` は Node のファイルハンドルを使い、非同期の読み書きとシークをオブジェクト単位で直列に実行します。
|
|
120
|
-
|
|
121
|
-
```typescript
|
|
122
|
-
import { FileInputStream, Image } from 'sfml.js';
|
|
123
|
-
|
|
124
|
-
async function readImage(filename: string) {
|
|
125
|
-
const stream = new FileInputStream();
|
|
126
|
-
try {
|
|
127
|
-
if (!await stream.open(filename)) throw new Error('Cannot open file');
|
|
128
|
-
const image = new Image();
|
|
129
|
-
if (!await image.loadFromStream(stream)) throw new Error('Cannot decode image');
|
|
130
|
-
return image;
|
|
131
|
-
} finally {
|
|
132
|
-
await stream.close();
|
|
133
|
-
}
|
|
134
|
-
}
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
読み込みの完了を待ってからストリームを閉じてください。同じストリームから複数回読み込む場合は、1 回ずつ await します。FileInputStream のファイルオフセットの範囲は 0~2⁵³−1 です。EOF でファイルが自動的に閉じることはなく、再度 seek できます。
|
|
138
|
-
|
|
139
|
-
## Unicode とバージョン
|
|
140
|
-
|
|
141
|
-
`Unicode.isGraphemeBoundary(text, position)`、`isWordBoundary()`、`isSentenceBoundary()` は SFML の Unicode 規則を使います。position は JS 文字列の UTF-16 インデックスで、範囲は 0~`text.length` です。サロゲートペアの途中は境界ではありません。
|
|
142
|
-
|
|
143
|
-
`version()` はキャッシュされた読み取り専用の SFML ランタイムバージョンを返し、`major`、`minor`、`patch`、`isRelease`、`string` を含みます。これは npm パッケージのバージョンではありません。
|
|
144
|
-
|
|
145
|
-
## エラーとログ
|
|
146
|
-
|
|
147
|
-
SFMLError はバインディング層または SFML の実行時エラーを表し、`instanceof SFMLError` で判定できます。引数のエラーには TypeError/RangeError を使い、ユーザーコールバックが投げたエラーはそのまま伝播します。SFML が返す通常の失敗ステータスは引き続き false/undefined であり、すべてが例外に変換されるわけではありません。
|
|
148
|
-
|
|
149
|
-
`err()` は `sf::err()` に書き込むシングルトンの Node Writable を返します。`setErrorOutput(writable)` で SFML のログをリダイレクトし、null を渡すと出力を抑止し、引数を省略すると既定の stderr に戻します。
|
|
150
|
-
|
|
151
|
-
```typescript
|
|
152
|
-
import { createWriteStream } from 'node:fs';
|
|
153
|
-
import { finished } from 'node:stream/promises';
|
|
154
|
-
import { err, setErrorOutput } from 'sfml.js';
|
|
155
|
-
|
|
156
|
-
const output = createWriteStream('sfml.log');
|
|
157
|
-
setErrorOutput(output);
|
|
158
|
-
err().write('SFML diagnostic\n');
|
|
159
|
-
setErrorOutput();
|
|
160
|
-
output.end();
|
|
161
|
-
await finished(output);
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
ログのルーティングはプロセス単位の設定であり、Worker も最後に設定された内容を共有します。Node 自身の stderr には影響しません。バックグラウンドのログはバイトチャンク単位で配送され、UTF-8 の文字境界や行境界は保証されません。テキストを解析する場合は StringDecoder を利用できます。
|
|
165
|
-
|
|
166
|
-
<a id="sfml-cpp-reference"></a>
|
|
167
|
-
## SFML C++ リファレンス
|
|
168
|
-
|
|
169
|
-
上流の [Vector2](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Vector2.html)、[Angle](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Angle.html)、[Time](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Time.html)、[Clock](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Clock.html)、[InputStream](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1InputStream.html) は、数学、時間、ストリームの概念を説明しています。JavaScript の名前付き演算関数、bigint による時間表現、Promise を返す sleep、ストリームのメソッドについては、このバインディングのガイドに従ってください。
|
package/docs/system.ko.md
DELETED
|
@@ -1,171 +0,0 @@
|
|
|
1
|
-
# System
|
|
2
|
-
|
|
3
|
-
[English](system.md) / [简体中文](system.zh-CN.md) / [日本語](system.ja.md) / **한국어**
|
|
4
|
-
|
|
5
|
-
> System은 값 타입, 시간, 입력 스트림, Unicode 경계, 오류 처리를 제공합니다. 일반적인 수치 계산은 JS에서 수행하며, 리소스 관련 작업은 인터페이스에 따라 네이티브 측에서 실행됩니다.
|
|
6
|
-
|
|
7
|
-
[API 안내](api.ko.md) · [핵심 개념](concepts.ko.md)
|
|
8
|
-
|
|
9
|
-
## 벡터와 연산
|
|
10
|
-
|
|
11
|
-
```typescript
|
|
12
|
-
import { Vector2f, Vector2i, add, multiply, addAssign } from 'sfml.js';
|
|
13
|
-
|
|
14
|
-
const position = new Vector2f(10, 20);
|
|
15
|
-
const velocity = new Vector2f(2, 3);
|
|
16
|
-
const next = add(position, velocity);
|
|
17
|
-
const doubled = multiply(velocity, 2);
|
|
18
|
-
addAssign(position, velocity);
|
|
19
|
-
const pixels = new Vector2i(position);
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
일반 연산은 독립적인 값을 반환하며, `*Assign`은 왼쪽 피연산자를 수정하고 반환합니다. 대입 시 벡터의 스칼라 타입이 자동 변환되지는 않습니다. 변환이 필요하면 해당 생성자를 사용하세요.
|
|
23
|
-
|
|
24
|
-
| 스칼라 태그 | JS 성분 타입 | 저장소 |
|
|
25
|
-
| --- | --- | --- |
|
|
26
|
-
| `i8`/`u8` | number | Int8Array/Uint8Array |
|
|
27
|
-
| `i16`/`u16` | number | Int16Array/Uint16Array |
|
|
28
|
-
| `i32`/`u32` | number | Int32Array/Uint32Array |
|
|
29
|
-
| `i64`/`u64` | bigint | BigInt64Array/BigUint64Array |
|
|
30
|
-
| `f32`/`f64` | number | Float32Array/Float64Array |
|
|
31
|
-
|
|
32
|
-
`Vector2i/u/f`와 `Vector3i/u/f`는 각각 i32/u32/f32에 대응합니다. 다른 스칼라는 `new Vector2('f64', x, y)`와 같은 형식으로 사용합니다.
|
|
33
|
-
|
|
34
|
-
두 벡터 타입 모두 `lengthSquared()`, `dot()`, `cross()`, 성분별 곱셈과 나눗셈을 제공합니다. 2차원 벡터에는 `perpendicular()`도 있습니다. 부동소수점 벡터는 `length()`와 `normalized()`를 제공하며, 부동소수점 2차원 벡터는 각도, 회전, 투영 연산도 제공합니다. 정수 벡터는 부동소수점 전용 메서드를 지원하지 않습니다.
|
|
35
|
-
|
|
36
|
-
벡터의 `multiply()`/`divide()`에는 스칼라를 사용하고, 성분별 연산에는 `componentWiseMul()`/`componentWiseDiv()`를 사용합니다. 0으로 나누기, 영벡터 정규화, 영벡터 축으로의 투영은 예외를 발생시킵니다. 64비트 정수 계산은 bigint를 유지합니다. f32 계산은 SFML의 정밀도 규칙에 따라 반올림되며, 삼각함수 연산에서는 플랫폼 수학 라이브러리에 따른 제한적인 차이가 허용됩니다.
|
|
37
|
-
|
|
38
|
-
## 각도
|
|
39
|
-
|
|
40
|
-
```typescript
|
|
41
|
-
import { Angle, degrees, radians, divide } from 'sfml.js';
|
|
42
|
-
|
|
43
|
-
const heading = degrees(90);
|
|
44
|
-
const turn = radians(Math.PI);
|
|
45
|
-
const copy = new Angle(heading);
|
|
46
|
-
const ratio = divide(turn, heading);
|
|
47
|
-
console.log(copy.asDegrees(), ratio);
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
회전 인터페이스는 Angle을 받습니다. `wrapSigned()`, `wrapUnsigned()`는 해당 범위로 래핑한 각도를 반환하지만, 비교 시에는 자동으로 래핑하지 않습니다. `Angle.Zero`는 읽기 전용 상수로, 복사한 뒤 수정할 수 있습니다. Angle은 float32를 사용하며, 나머지 연산의 제수는 양수여야 합니다.
|
|
51
|
-
|
|
52
|
-
## 시간과 시계
|
|
53
|
-
|
|
54
|
-
```typescript
|
|
55
|
-
import { Clock, milliseconds, microseconds, sleep } from 'sfml.js';
|
|
56
|
-
|
|
57
|
-
const clock = new Clock();
|
|
58
|
-
await sleep(milliseconds(16));
|
|
59
|
-
const elapsed = clock.restart();
|
|
60
|
-
console.log(elapsed.asSeconds(), elapsed.asMicroseconds());
|
|
61
|
-
console.log(microseconds(1000n).asMilliseconds());
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
| 인터페이스 | 의미 |
|
|
65
|
-
| --- | --- |
|
|
66
|
-
| `new Time()`/`new Time(source)`/`new Time(bigint)` | 길이가 0인 시간, 복사, 마이크로초로 생성 |
|
|
67
|
-
| `seconds(number)` | 초를 Time으로 변환 |
|
|
68
|
-
| `milliseconds(number)` | int32 밀리초 입력. 소수 부분은 0 방향으로 버림 |
|
|
69
|
-
| `microseconds(bigint)` | 마이크로초 입력 |
|
|
70
|
-
| `asMicroseconds()`/`toDuration()` | 마이크로초 bigint |
|
|
71
|
-
| `asSeconds()`/`asMilliseconds()` | float32 초/int32 밀리초 |
|
|
72
|
-
| `Clock.start()`/`stop()` | 시간 측정 재개/일시 정지 |
|
|
73
|
-
| `Clock.restart()`/`reset()` | 기존 경과 시간을 반환하고 0으로 초기화한 뒤 실행/일시 정지 |
|
|
74
|
-
|
|
75
|
-
Time은 부호 있는 int64 마이크로초를 저장하며, 정수 배수 연산에는 bigint를, 부동소수점 배수에는 number를 사용합니다. `Time.Zero`는 읽기 전용 상수입니다. 범위를 벗어나거나 잘못된 나눗셈을 수행하면 RangeError가 발생하며, 제자리 연산이 실패하면 원래 값을 유지합니다.
|
|
76
|
-
|
|
77
|
-
Clock은 `process.hrtime.bigint()`를 사용하고 독립적인 Time 스냅샷을 반환합니다. 자체 타이머는 없으며, 시계 해상도와 시스템 절전 중의 동작은 Node.js와 플랫폼에 따라 결정됩니다.
|
|
78
|
-
|
|
79
|
-
`sleep(time)`은 Promise를 반환하고 Node 타이머로 기다리며 이벤트 루프를 차단하지 않습니다. 양수 시간은 밀리초 단위로 올림합니다. 0이나 음수 시간은 즉시 완료되며, 실제 재개 시점은 스케줄링의 영향을 받습니다.
|
|
80
|
-
|
|
81
|
-
### 타임아웃 설정
|
|
82
|
-
|
|
83
|
-
`TimeoutWithPredicate`는 확인 주기와 조건 함수를 저장할 뿐, 자체적으로 타이머를 시작하지 않습니다.
|
|
84
|
-
|
|
85
|
-
- `new TimeoutWithPredicate(time)`: 고정 주기이며 조건 함수는 항상 false를 반환합니다.
|
|
86
|
-
- `new TimeoutWithPredicate(predicate, period?)`: 기본 주기는 1 ms이며, true는 계속 기다린다는 뜻입니다.
|
|
87
|
-
- `getPeriod()`는 읽기 전용 Time을, `getPredicate()`는 원본 함수를 반환합니다.
|
|
88
|
-
|
|
89
|
-
이를 받는 인터페이스가 확인 시점을 결정합니다. 현재 SFTP는 진행이 없는 동안의 대기를 제어하는 데 사용합니다. 자세한 내용은 [Network](network.ko.md#sftp)를 참고하세요.
|
|
90
|
-
|
|
91
|
-
`SuspendAwareClock.now()`는 시스템 절전 시간을 포함하는 네이티브 나노초 시점을 반환하며, Android 분기에서만 지원됩니다. 데스크톱에서 호출하면 SFMLError가 발생합니다. 현재 자동 다운로드 절차에는 Android 빌드 대상이 없습니다.
|
|
92
|
-
|
|
93
|
-
## 색상, 사각형, 정점
|
|
94
|
-
|
|
95
|
-
| 타입 | 생성 및 주요 연산 |
|
|
96
|
-
| --- | --- |
|
|
97
|
-
| Color | RGB/RGBA, `0xRRGGBBAA`, 복사; `r/g/b/a`, `toInteger()` |
|
|
98
|
-
| FloatRect/IntRect | `position` + `size`, 복사, 명시적 변환; `contains()`, `findIntersection()`, `getCenter()` |
|
|
99
|
-
| Vertex | `position`, `color`, `texCoords` 또는 복사 생성 |
|
|
100
|
-
|
|
101
|
-
이 값들은 주로 그래픽 인터페이스에서 사용합니다. Color 성분은 uint8로 저장되며, 직접 쓰면 해당 비트 폭으로 축소됩니다. 색상 덧셈과 뺄셈은 포화 연산이고, 색상 곱셈은 채널별로 `floor(a * b / 255)`를 계산합니다. Color 상수는 읽기 전용입니다.
|
|
102
|
-
|
|
103
|
-
사각형과 정점의 멤버는 공유 뷰입니다. 사각형은 왼쪽과 위쪽 경계를 포함하고 오른쪽과 아래쪽 경계는 제외합니다. 음수 크기는 정규화된 범위로 계산하며, 교집합의 면적이 양수가 아니면 `undefined`를 반환합니다. Vertex의 기본 위치와 텍스처 좌표는 0이고, 색상은 흰색입니다.
|
|
104
|
-
|
|
105
|
-
<a id="input-streams"></a>
|
|
106
|
-
## 입력 스트림
|
|
107
|
-
|
|
108
|
-
InputStream은 탐색 가능한 바이트 스트림 프로토콜이며, 메서드는 동기식 값이나 Promise를 반환할 수 있습니다.
|
|
109
|
-
|
|
110
|
-
| 메서드 | 반환값 |
|
|
111
|
-
| --- | --- |
|
|
112
|
-
| `read(data)` | Uint8Array에 쓰고 실제 바이트 수를 bigint로 반환. EOF는 `0n` |
|
|
113
|
-
| `seek(position)` | 실제 바이트 위치를 bigint로 반환 |
|
|
114
|
-
| `tell()` | 현재 바이트 위치 bigint |
|
|
115
|
-
| `getSize()` | 전체 바이트 수 bigint |
|
|
116
|
-
|
|
117
|
-
`undefined`는 I/O 실패를 뜻하며, 발생한 오류는 그대로 전파됩니다. 이 네 메서드를 구현한 객체도 스트림으로 전달할 수 있습니다. Node Readable에는 탐색 기능을 추가로 구현해야 합니다.
|
|
118
|
-
|
|
119
|
-
`MemoryInputStream(data)`는 입력 바이트의 참조를 유지합니다. 로딩 중에는 내용을 변경하지 말고, 한 작업이 커서를 독점하도록 하세요. `FileInputStream`은 Node 파일 핸들을 사용하며, 객체별로 비동기 읽기/쓰기와 탐색을 직렬 실행합니다.
|
|
120
|
-
|
|
121
|
-
```typescript
|
|
122
|
-
import { FileInputStream, Image } from 'sfml.js';
|
|
123
|
-
|
|
124
|
-
async function readImage(filename: string) {
|
|
125
|
-
const stream = new FileInputStream();
|
|
126
|
-
try {
|
|
127
|
-
if (!await stream.open(filename)) throw new Error('Cannot open file');
|
|
128
|
-
const image = new Image();
|
|
129
|
-
if (!await image.loadFromStream(stream)) throw new Error('Cannot decode image');
|
|
130
|
-
return image;
|
|
131
|
-
} finally {
|
|
132
|
-
await stream.close();
|
|
133
|
-
}
|
|
134
|
-
}
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
로딩이 완료될 때까지 기다린 뒤 스트림을 닫으세요. 같은 스트림에서 여러 번 로드할 때는 하나씩 await해야 합니다. FileInputStream의 파일 오프셋 범위는 0~2⁵³−1입니다. EOF에서 파일을 자동으로 닫지 않으므로 다시 seek할 수 있습니다.
|
|
138
|
-
|
|
139
|
-
## Unicode와 버전
|
|
140
|
-
|
|
141
|
-
`Unicode.isGraphemeBoundary(text, position)`, `isWordBoundary()`, `isSentenceBoundary()`는 SFML의 Unicode 규칙을 사용합니다. position은 JS 문자열의 UTF-16 인덱스로, 범위는 0~`text.length`입니다. 서로게이트 쌍의 중간은 경계가 아닙니다.
|
|
142
|
-
|
|
143
|
-
`version()`은 캐시된 읽기 전용 SFML 런타임 버전을 반환하며, `major`, `minor`, `patch`, `isRelease`, `string`을 포함합니다. npm 패키지 버전은 아닙니다.
|
|
144
|
-
|
|
145
|
-
## 오류와 로그
|
|
146
|
-
|
|
147
|
-
SFMLError는 바인딩 계층이나 SFML의 실행 실패를 나타내며, `instanceof SFMLError`로 판별할 수 있습니다. 매개변수 오류에는 TypeError/RangeError를 사용하고, 사용자 콜백의 오류는 그대로 전파됩니다. SFML이 반환하는 일반적인 실패 상태는 여전히 false/undefined이며, 전부 예외로 변환되지는 않습니다.
|
|
148
|
-
|
|
149
|
-
`err()`는 `sf::err()`에 쓰는 싱글턴 Node Writable을 반환합니다. `setErrorOutput(writable)`은 SFML 로그를 리디렉션하며, null을 전달하면 출력을 끄고 인수 없이 호출하면 기본 stderr로 복원합니다.
|
|
150
|
-
|
|
151
|
-
```typescript
|
|
152
|
-
import { createWriteStream } from 'node:fs';
|
|
153
|
-
import { finished } from 'node:stream/promises';
|
|
154
|
-
import { err, setErrorOutput } from 'sfml.js';
|
|
155
|
-
|
|
156
|
-
const output = createWriteStream('sfml.log');
|
|
157
|
-
setErrorOutput(output);
|
|
158
|
-
err().write('SFML diagnostic\n');
|
|
159
|
-
setErrorOutput();
|
|
160
|
-
output.end();
|
|
161
|
-
await finished(output);
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
로그 경로는 프로세스 전체 설정이며 Worker도 가장 최근의 설정을 공유합니다. Node 자체의 stderr에는 영향을 주지 않습니다. 백그라운드 로그는 바이트 청크 단위로 전달되어 UTF-8 문자 경계나 줄 경계가 보장되지 않으므로, 텍스트를 파싱할 때는 StringDecoder를 사용할 수 있습니다.
|
|
165
|
-
|
|
166
|
-
<a id="sfml-cpp-reference"></a>
|
|
167
|
-
## SFML C++ 레퍼런스
|
|
168
|
-
|
|
169
|
-
원본 클래스 문서: [Vector2](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Vector2.html), [Angle](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Angle.html), [Time](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Time.html), [Clock](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Clock.html), [InputStream](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1InputStream.html).
|
|
170
|
-
|
|
171
|
-
C++ 레퍼런스는 수학, 시간, 스트림의 기본 개념을 설명합니다. JS의 이름 있는 연산자, bigint 시간 표현, Promise 기반 sleep, 스트림 메서드의 구체적인 동작은 이 바인딩의 가이드를 따르세요.
|