sfml.js 1.0.0 → 1.2.1
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 +44 -51
- 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/audio.zh-CN.md
DELETED
|
@@ -1,252 +0,0 @@
|
|
|
1
|
-
# Audio
|
|
2
|
-
|
|
3
|
-
[English](audio.md) · **简体中文** · [日本語](audio.ja.md) · [한국어](audio.ko.md)
|
|
4
|
-
|
|
5
|
-
> 短音效使用 SoundBuffer + Sound,长音频使用 Music。自定义供数、录音处理和音效通过 Node Worker 执行。
|
|
6
|
-
|
|
7
|
-
[API 导航](api.zh-CN.md) · [核心概念](concepts.zh-CN.md) · [示例](../examples/README.zh-CN.md)
|
|
8
|
-
|
|
9
|
-
## 选择接口
|
|
10
|
-
|
|
11
|
-
| 任务 | 接口 |
|
|
12
|
-
| --- | --- |
|
|
13
|
-
| 加载并重复播放短音效 | SoundBuffer、Sound |
|
|
14
|
-
| 流式播放文件、内存或输入流 | Music |
|
|
15
|
-
| 自行生成 PCM | SoundStream + Worker 模块 |
|
|
16
|
-
| 调整音量、声像与空间属性 | SoundSource、Listener |
|
|
17
|
-
| 选择播放设备 | PlaybackDevice |
|
|
18
|
-
| 录音到缓冲区 | SoundBufferRecorder |
|
|
19
|
-
| 自行处理采集数据 | SoundRecorder + Worker 模块 |
|
|
20
|
-
| 处理音源输出 | EffectProcessor |
|
|
21
|
-
| 读写音频文件或扩展格式 | InputSoundFile、OutputSoundFile、SoundFileFactory |
|
|
22
|
-
|
|
23
|
-
文件和压缩数据使用「空构造 + await open/load」。SoundBuffer 与 Sound 提供复制构造,SoundBuffer 还可以从 PCM 构造。完整签名见 [TypeDoc](https://sfml.js.org/zh/reference/)。
|
|
24
|
-
|
|
25
|
-
## 播放短音效
|
|
26
|
-
|
|
27
|
-
```js
|
|
28
|
-
const sf = require('sfml.js');
|
|
29
|
-
|
|
30
|
-
async function play() {
|
|
31
|
-
const buffer = new sf.SoundBuffer();
|
|
32
|
-
if (!await buffer.loadFromFile('sound.wav')) {
|
|
33
|
-
throw new Error('Cannot load sound.wav');
|
|
34
|
-
}
|
|
35
|
-
const sound = new sf.Sound(buffer);
|
|
36
|
-
sound.setVolume(25);
|
|
37
|
-
sound.play();
|
|
38
|
-
while (sound.getStatus() === sf.SoundStatus.Playing) {
|
|
39
|
-
await sf.sleep(sf.milliseconds(10));
|
|
40
|
-
}
|
|
41
|
-
}
|
|
42
|
-
play().catch(error => {
|
|
43
|
-
console.error(error);
|
|
44
|
-
process.exitCode = 1;
|
|
45
|
-
});
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
用 `setLooping()` 控制循环,`setPlayingOffset()` 调整播放位置。多个 Sound 可以共用同一个 SoundBuffer;复制 Sound 不会共享 Worker 音效。
|
|
49
|
-
|
|
50
|
-
## 播放音乐
|
|
51
|
-
|
|
52
|
-
以下片段放在 async 函数内运行:
|
|
53
|
-
|
|
54
|
-
```javascript
|
|
55
|
-
const music = new sf.Music();
|
|
56
|
-
try {
|
|
57
|
-
if (!await music.openFromFile('music.ogg')) {
|
|
58
|
-
throw new Error('Cannot open music.ogg');
|
|
59
|
-
}
|
|
60
|
-
music.play();
|
|
61
|
-
await sf.sleep(sf.seconds(5));
|
|
62
|
-
} finally {
|
|
63
|
-
await music.close();
|
|
64
|
-
}
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
Music 继承 SoundStream,提供时长和循环区间。读取 getter 返回的 Time 不会直接修改播放位置,需要调用 setter。
|
|
68
|
-
|
|
69
|
-
## PCM 与共享内存
|
|
70
|
-
|
|
71
|
-
`getSamples()` 返回映射 `sf::SoundBuffer::getSamples()` 的 Int16Array,空缓冲返回 undefined。音频样本采用交错声道排列,sampleCount 包含全部声道,使用 bigint;采样率与声道数使用 number。duration 和 playingOffset 使用 Time。
|
|
72
|
-
|
|
73
|
-
SoundBuffer 的 sampleRate、duration 直接映射稳定的 SFML 字段,样本数和声道数存于 Native 派生字段。Cone、TimeSpan、SoundFileReader.Info 的数值映射各自的 Native 结构。SoundSource、Listener 使用稳定的 Native 数值控制区传递参数和结果,每次控制操作仍调用 SFML setter/getter,使音频引擎执行同步、换算与状态更新。位置、方向、Cone、Time 返回独立值;修改 getter 的结果不会改变音源。
|
|
74
|
-
|
|
75
|
-
PCM 和只读 channelMap 视图的 BackingStore 保活对应的 Native 分配。SoundBuffer 成功重载后,旧视图继续指向旧分配,关联 Sound 切换到新缓冲;失败加载保留当前资源。SoundBufferRecorder 每次录音使用新的 Native recorder,结束时直接映射其 `getBuffer()`,旧录音视图继续有效。
|
|
76
|
-
|
|
77
|
-
`new SoundBuffer(samples, channelCount, sampleRate, channelMap)` 从 Int16Array 同步构造,使用数组视图的长度作为样本数,SFML 复制样本,加载失败抛出 SFMLError。
|
|
78
|
-
|
|
79
|
-
`target.assign(source)` 在 Native 中深拷贝 source 当前的样本和元数据,返回 target。目标 JS 对象和 Native 句柄保持不变,关联 Sound 重新绑定到目标的新分配;此前取得的样本和声道视图继续保活旧分配。source 可以是录音返回的 ReadonlySoundBuffer;自赋值直接返回,不改变视图或播放状态。该方法和 `loadFromSamples()` 都同步替换当前资源;已经提交的异步加载成功完成后仍会发布其结果,需要固定操作顺序时先 await 加载。
|
|
80
|
-
|
|
81
|
-
```js
|
|
82
|
-
const source = new sf.SoundBuffer(
|
|
83
|
-
new Int16Array([ 1000, -1000, 500, -500 ]),
|
|
84
|
-
1, 44100, [ sf.SoundChannel.Mono ],
|
|
85
|
-
);
|
|
86
|
-
const target = new sf.SoundBuffer();
|
|
87
|
-
target.assign(source);
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
ReadonlySamples、ChannelMap 和 ReadonlySoundBuffer 的只读约束作用于 TypeScript 类型。运行时没有逐样本 Proxy;不要通过 JS 强制写入、分离或转移这些只读视图的底层 buffer。需要独立可写数据时使用 `slice()`。
|
|
91
|
-
|
|
92
|
-
`loadFromSamples()` 同步调用 SFML,SFML 持有复制后的样本。异步内存加载、文件 read/write 保留操作涉及的底层分配,调用者在 Promise 完成前不得修改、分离或调整输入/输出缓冲。`Music.openFromMemory()` 和 `InputSoundFile.openFromMemory()` 的压缩数据在资源关闭或重新打开前都必须保持不变。
|
|
93
|
-
|
|
94
|
-
## 音源拷贝赋值
|
|
95
|
-
|
|
96
|
-
`SoundSource.assign(source)` 同步复制音高、声像、音量、空间化、位置、方向、声锥、速度、多普勒、方向衰减系数、相对位置模式、距离、增益和衰减设置,返回目标自身。Music 和自定义 SoundStream 继承该方法。目标内容、循环设置、播放位置、播放状态和音效保留,源不受影响。复制在一次 Native 调用中完成,SFML setter 更新引擎,控制区 fast buffer 保持原映射。
|
|
97
|
-
|
|
98
|
-
`Sound.assign(sourceSound)` 接受 Sound,同步复制上述属性、循环设置和 SoundBuffer 绑定。两个 Sound 引用同一个缓冲,赋值更新 JS 引用及 Native 保活和关联列表;目标停止并归零,源播放不变。目标保留自己的 EffectProcessor,已有音效队列通过更新代数失效,随后丢弃旧块。目标 Native sf::Sound 实例和控制区保持不变。
|
|
99
|
-
|
|
100
|
-
两种 assign 均在自赋值时直接返回。需要对 Sound 只复制基类属性时,可以显式调用 `SoundSource.prototype.assign.call(targetSound, source)`;将变量标注为 SoundSource 不会改变 JS 的动态方法分派。
|
|
101
|
-
|
|
102
|
-
SFML 3.1.0 的 `SoundSource::operator=` 未复制 directionalAttenuationFactor,本绑定的属性复制包含该字段。
|
|
103
|
-
|
|
104
|
-
```js
|
|
105
|
-
music.assign(sound); // 复制音源属性,保留 music 的内容与播放状态。
|
|
106
|
-
targetSound.assign(sourceSound); // 绑定相同缓冲,targetSound 停止并归零。
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
## Worker 供数
|
|
110
|
-
|
|
111
|
-
所有 Audio Worker 使用模块工厂,支持 CommonJS 和 ESM。`module` 为文件路径或 URL;`exportName` 默认为 `default`;`data` 按 Worker 的 structured clone 规则传入。工厂接收 `{ sampleRate, channelCount, blockFrames }` 和 data,返回对应的回调对象,可以返回 Promise。
|
|
112
|
-
|
|
113
|
-
仓库中的 [audio-worker.cjs](../examples/audio-worker.cjs) 提供可运行的 `tone` 和 `filter` 工厂。
|
|
114
|
-
|
|
115
|
-
```js
|
|
116
|
-
const path = require('node:path');
|
|
117
|
-
const sf = require('sfml.js');
|
|
118
|
-
|
|
119
|
-
async function playStream() {
|
|
120
|
-
const stream = new sf.SoundStream({
|
|
121
|
-
module: path.resolve('examples/audio-worker.cjs'),
|
|
122
|
-
exportName: 'tone',
|
|
123
|
-
data: { frequency: 330 },
|
|
124
|
-
sampleRate: 44100,
|
|
125
|
-
channelCount: 1,
|
|
126
|
-
channelMap: [ sf.SoundChannel.Mono ],
|
|
127
|
-
blockFrames: 1024,
|
|
128
|
-
queueBlocks: 8,
|
|
129
|
-
});
|
|
130
|
-
try {
|
|
131
|
-
if (!await stream.ready) return;
|
|
132
|
-
stream.play();
|
|
133
|
-
await sf.sleep(sf.seconds(2));
|
|
134
|
-
} finally {
|
|
135
|
-
await stream.close();
|
|
136
|
-
}
|
|
137
|
-
}
|
|
138
|
-
playStream().catch(error => {
|
|
139
|
-
console.error(error);
|
|
140
|
-
process.exitCode = 1;
|
|
141
|
-
});
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
| 回调 | 契约 |
|
|
145
|
-
|------|------|
|
|
146
|
-
| `onGetData(chunk)` | 填写 Native 提供的 `chunk.samples`,设置 `chunk.sampleCount`;true 表示继续,false 表示最后一块 |
|
|
147
|
-
| `onSeek(time)` | 将生产游标定位到 Time;初始化也会调用一次 |
|
|
148
|
-
| `onLoop()` | 在最后一块准备阶段调用;返回交错样本偏移 bigint,undefined 禁止本轮循环;省略时默认返回 `0n` |
|
|
149
|
-
| `onClose()` | Worker 退出前清理资源 |
|
|
150
|
-
|
|
151
|
-
不能替换 `chunk.samples`。sampleCount 不得超过槽位容量,必须是声道数的整数倍;继续供数时不能提交零样本。最后一块可以携带有效样本。Native 在 seek 时更新代数,设备线程丢弃此前已经排队的数据;Worker 随后执行新的 onSeek。
|
|
152
|
-
|
|
153
|
-
回调获得的 TypedArray 是可复用 Native 槽位,只在本次回调完成前由该回调独占。不要保留后继续访问,必须保留内容时自行 `slice()`。Promise 完成才会提交或释放槽位。回调必须最终完成;未完成的用户 Promise 会阻止正常 `close()` 或录音排空。
|
|
154
|
-
|
|
155
|
-
## 音效
|
|
156
|
-
|
|
157
|
-
下面的片段接续已创建的 Sound,并在 async 函数中运行;`path` 为 `node:path`,Worker 模块路径以仓库根目录为基准。
|
|
158
|
-
|
|
159
|
-
```js
|
|
160
|
-
const effect = new sf.EffectProcessor({
|
|
161
|
-
module: path.resolve('examples/audio-worker.cjs'),
|
|
162
|
-
exportName: 'filter',
|
|
163
|
-
blockFrames: 1024,
|
|
164
|
-
queueBlocks: 8,
|
|
165
|
-
maxChannelCount: 8,
|
|
166
|
-
});
|
|
167
|
-
await effect.ready;
|
|
168
|
-
sound.setEffectProcessor(effect);
|
|
169
|
-
// 完成使用后,先从音源移除,再结束 Worker。
|
|
170
|
-
sound.setEffectProcessor();
|
|
171
|
-
await effect.close();
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
音效工厂返回 `process(input, inputFrameCount, output, outputFrameCount, channelCount)`。input 和 output 是 Native float32 队列映射,输入已经过空间化,channelCount 是本次设备输出声道数。返回 `{ inputFrameCount, outputFrameCount }` 指定实际消费和产出帧数,允许部分消费;返回 void 表示消费全部输入并输出同等帧数。非尾音调用必须消费或产出至少一帧。
|
|
175
|
-
|
|
176
|
-
input 为 null 表示尾音处理,可输出残响,最终返回零输出帧结束尾音。每帧有 channelCount 个交错 float32 样本;只能访问本次传入的有效视图。`maxChannelCount` 是预分配容量,默认 8;实际声道数超过容量时输出静音。工厂 context 中的 channelCount 是容量,实际处理以 process 参数为准;sampleRate 在创建 Worker 时读取,设备切换后需要重新创建依赖采样率的音效。
|
|
177
|
-
|
|
178
|
-
一个 EffectProcessor 同时只能安装到一个音源。移除后可以安装到其他音源。安装和移除会保留音源的播放位置与播放/暂停状态。显式关闭仍安装着的 EffectProcessor 后,该音源的音效通路输出静音。
|
|
179
|
-
|
|
180
|
-
## 录音
|
|
181
|
-
|
|
182
|
-
以下片段在 async 函数内运行,`sf` 为包导入。先确认采集设备可用,并允许系统麦克风权限:
|
|
183
|
-
|
|
184
|
-
```js
|
|
185
|
-
const recorder = new sf.SoundBufferRecorder();
|
|
186
|
-
recorder.setChannelCount(1);
|
|
187
|
-
try {
|
|
188
|
-
if (!await recorder.start(44100)) throw new Error('Cannot start recording');
|
|
189
|
-
await sf.sleep(sf.seconds(1));
|
|
190
|
-
} finally {
|
|
191
|
-
await recorder.stop();
|
|
192
|
-
}
|
|
193
|
-
const recorded = recorder.getBuffer();
|
|
194
|
-
console.log(recorded.getSampleCount());
|
|
195
|
-
if (!await recorded.saveToFile('recorded.wav')) throw new Error('Cannot save recording');
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
`start()`、`stop()`、`setDevice()` 返回 Promise;声道数支持 1 或 2,修改前先停止录音并等待待处理操作。播放与采集设备分开查询和选择。
|
|
199
|
-
|
|
200
|
-
自定义 SoundRecorder 使用与 SoundStream 相同的 Worker 配置,工厂返回可选 `onStart()`、必需 `onProcessSamples(samples)`、可选 `onStop()`。onStart 返回 false 取消启动。onProcessSamples 接收只在回调期间有效的 Native Int16Array;返回 false 后由异步任务停止采集。正常 `await stop()` 等待队列排空和 onStop 完成;回调主动返回 false 时丢弃剩余排队样本。
|
|
201
|
-
|
|
202
|
-
## 文件流与编解码扩展
|
|
203
|
-
|
|
204
|
-
SoundBuffer、Music、InputSoundFile 都支持现有 InputStream、MemoryInputStream 和 FileInputStream。文件读写、打开与关闭按对象串行,跨对象可并行。成功打开后才发布 Native 元数据;异步 read/seek 完成前 getter 仍返回上一份已发布结果。
|
|
205
|
-
|
|
206
|
-
内置 SFML 文件/内存解码在线程中执行。异步 InputStream 使用独立 Native 解码线程和 libuv 通知桥接,避免等待 JS 文件 I/O 时占满 libuv 工作线程池。InputStream 的 read 目的缓冲由 Native 分配,完成时取得有效字节快照。
|
|
207
|
-
|
|
208
|
-
Music 的普通文件/内存输入使用 `sf::Music`。InputStream 或已注册 JS Reader 的输入使用有界 PCM 预取,默认 1024 帧、8 个槽位;异步解码在设备回调外执行,播放、定位和循环通过 Native SoundStream 消费。JS 自定义 Reader 运行在调用环境,耗时的同步 JS 解码会占用该环境的事件循环。
|
|
209
|
-
|
|
210
|
-
SFML 内置 Reader/Writer 由 SoundFileFactory 创建后仍需调用 `open()`。WAV、FLAC、Ogg 写入与读回已有运行测试;其他 SFML 内置输入格式沿用当前 SFML 构建的解码支持。
|
|
211
|
-
|
|
212
|
-
扩展 Reader 继承 SoundFileReader,提供静态 `check(stream)`、`open(stream)`、`seek(sampleOffset)`、`read(samples)` 和可选 `close()`。open 返回 `new SoundFileReader.Info({ sampleCount, sampleRate, channelCount, channelMap })` 或 undefined。read 填写传入 Int16Array,返回实际样本数 bigint。扩展 Writer 继承 SoundFileWriter,提供静态 `check(filename)`、`open(filename, sampleRate, channelCount, channelMap)`、`write(samples)` 和可选 `close()`。这些方法可以返回 Promise。
|
|
213
|
-
|
|
214
|
-
通过 `SoundFileFactory.registerReader(ReaderClass)` 和 `registerWriter(WriterClass)` 注册,使用对应 unregister 方法注销;重复注册同一类不会重复插入。JS 注册表属于当前 Node 环境,Worker 需要在自身环境注册。所有公开 SoundBuffer、Music 和音频文件入口先检测注册的 JS 类,未匹配时回退到 SFML 内置工厂。模板注册接口通过 JS 类实现,不会把 JS 函数指针安装进进程级 C++ 工厂。完整扩展示例见 [audio-codec.test.cjs](../test/audio-codec.test.cjs)。
|
|
215
|
-
|
|
216
|
-
## 缓冲、状态与清理
|
|
217
|
-
|
|
218
|
-
Worker 默认 `blockFrames = 1024`、`queueBlocks = 8`。允许 64~65536 帧、2~32 槽位、1~32 声道。槽位内存由 Native 预分配,通过 acquire/release 发布和归还,PCM 不经过 postMessage 复制。postMessage 只传递 ready、错误和停止通知。
|
|
219
|
-
|
|
220
|
-
1024 帧在 44100 Hz 下为 23.22 ms,8 槽位可容纳约 185.76 ms 的样本。这里是块时长和队列容量,不是端到端延迟保证。Worker 每 2 ms 异步检查可用槽位,设备输出还受 SFML 与系统缓冲影响。
|
|
221
|
-
|
|
222
|
-
| 情况 | 行为与统计单位 |
|
|
223
|
-
|------|----------------|
|
|
224
|
-
| Stream 缺少已就绪的 PCM | 输出静音;underruns 统计缺块次数 |
|
|
225
|
-
| 录音队列已满 | 丢弃新增样本;overruns 统计交错样本数 |
|
|
226
|
-
| 音效输入队列已满 | 丢弃本次接收的输入帧;overruns 统计帧数 |
|
|
227
|
-
| 音效输出不足 | 缺少部分补静音;underruns 统计帧数 |
|
|
228
|
-
| processed | Stream/Recorder 为交错样本数,EffectProcessor 为消费的输入帧数 |
|
|
229
|
-
|
|
230
|
-
`getWorkerStats()` 返回 bigint 统计快照,`getWorkerError()` 返回已记录的异步错误。Worker 初始化错误使 ready 拒绝;close/stop 会报告 Worker 错误。C++ 异常映射为 SFMLError,SFML 诊断写入已有 `err()`/`setErrorOutput()` 通路。
|
|
231
|
-
|
|
232
|
-
Audio Worker 在初始化完成后 unref,不会独自维持 Node 进程;播放期间用窗口循环或 `await sleep()` 保持事件循环。结束时使用 `await stream.close()`、`await music.close()`、`await effect.close()`、`await recorder.stop()`。文件写入使用 `await output.close()` 完成尾部和资源清理。Native 音源与录音资源沿用项目的后台释放机制;视图保活对应分配,Node 环境退出会结束所属资源。
|
|
233
|
-
|
|
234
|
-
播放设备通知在注册回调的 JS 线程异步派发,不在音频设备线程执行。SFML 的通知回调是进程级单槽位,最后一次注册替代此前注册;调用 `setNotificationCallback()` 移除并丢弃待派发通知。
|
|
235
|
-
|
|
236
|
-
## 演示与验证
|
|
237
|
-
|
|
238
|
-
执行 `npm run demo:audio`,或构建后运行 `node examples/audio.cjs`。1~4 切换 Sound、WorkerStream、Music 和录音回放;Space 播放/暂停,S 停止,E 切换音效,R 开始录音,T 结束录音;方向键控制声像和音量。Esc 关闭。录音只保留在内存中。
|
|
239
|
-
|
|
240
|
-
`node examples/audio.cjs --smoke --frames=90` 自动验证扬声器播放、Worker PCM、音效处理、Music、麦克风录音与回放,随后退出。该模式会启用本机采集设备。普通启动等待用户按键。
|
|
241
|
-
|
|
242
|
-
自动测试覆盖 SFML 字段对照、PCM 视图、资源生命周期、WAV/FLAC/Ogg、异步输入流、Worker 供数与定位、音效、录音队列和自定义编解码。测试代码见 [test/audio.test.cjs](../test/audio.test.cjs)、[Worker 测试](../test/audio-worker.test.cjs) 及 [编解码测试](../test/audio-codec.test.cjs)。
|
|
243
|
-
|
|
244
|
-
声音实际输出、麦克风采集和设备热插拔需要在目标设备验证。CI 的构建与测试配置见 [开发指南](development.zh-CN.md#testing)。
|
|
245
|
-
|
|
246
|
-
<a id="sfml-cpp-reference"></a>
|
|
247
|
-
|
|
248
|
-
## SFML C++ 参考
|
|
249
|
-
|
|
250
|
-
播放与资源参考 [sf::SoundBuffer](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1SoundBuffer.html)、[sf::Sound](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Sound.html) 和 [sf::Music](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Music.html);扩展能力参考 [sf::SoundStream](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1SoundStream.html)、[sf::SoundRecorder](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1SoundRecorder.html) 和 [sf::SoundFileFactory](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1SoundFileFactory.html)。
|
|
251
|
-
|
|
252
|
-
上游文档可用于理解播放、声道和空间音频概念。JS 资源方法的异步行为、Worker 回调形式及共享缓冲有效期按本文执行,不直接套用 C++ 回调与析构方式。
|
package/docs/concepts.ja.md
DELETED
|
@@ -1,130 +0,0 @@
|
|
|
1
|
-
# 基本概念
|
|
2
|
-
|
|
3
|
-
[English](concepts.md) / [简体中文](concepts.zh-CN.md) / **日本語** / [한국어](concepts.ko.md)
|
|
4
|
-
|
|
5
|
-
> sfml.js を使う際は、まず値、リソース、ビューを区別し、次にコマンドの記録、送信、表示を区別してください。これらの境界が、コピー、非同期読み込み、描画の挙動を決定します。
|
|
6
|
-
|
|
7
|
-
[ドキュメントトップ](README.ja.md) · [API ナビゲーション](api.ja.md)
|
|
8
|
-
|
|
9
|
-
## 値、リソース、ビュー
|
|
10
|
-
|
|
11
|
-
ベクトル、角度、色、矩形、頂点、行列などの値型は、最初は JS の TypedArray に格納されます。数学的な計算は JavaScript で行い、ネイティブハンドルが必要になったときにだけ、同じメモリをラップします。`Time` はマイクロ秒単位の `bigint` を使います。
|
|
12
|
-
|
|
13
|
-
Texture、Image、Sprite、Text、オーディオオブジェクトなどのリソースはネイティブ側で管理します。JS のラッパーオブジェクトと存続中のビューが、関連するメモリ割り当てを維持します。リソースの解放は、所属スレッドと基盤となる依存リソースのライフサイクルに従います。
|
|
14
|
-
|
|
15
|
-
```typescript
|
|
16
|
-
import { FloatRect, Vector2f } from 'sfml.js';
|
|
17
|
-
|
|
18
|
-
const rect = new FloatRect(new Vector2f(10, 20), new Vector2f(100, 80));
|
|
19
|
-
const member = rect.position;
|
|
20
|
-
member.x = 30; // メンバービューなので rect を変更する。
|
|
21
|
-
|
|
22
|
-
const copy = new Vector2f(member);
|
|
23
|
-
copy.x = 90; // 独立したコピーなので rect に影響しない。
|
|
24
|
-
|
|
25
|
-
rect.position = new Vector2f(5, 6); // 値をコピーする。member は引き続き rect のメンバーを指す。
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
通常の JS の代入は参照の代入です。独立した値が必要な場合はコピーコンストラクターを使います。リソースのコピー規則はクラスによって異なります。たとえば `new Texture(texture)` は GPU 上の内容をコピーしますが、`new Sprite(sprite)` はスプライトのプロパティをコピーし、テクスチャは共有します。
|
|
29
|
-
|
|
30
|
-
戻り値が独立しているかどうかを `get...()` という名前だけで判断しないでください。
|
|
31
|
-
|
|
32
|
-
| 読み取り方法 | 所有権と更新の挙動 |
|
|
33
|
-
| --- | --- |
|
|
34
|
-
| `sprite.getPosition()` | 独立したベクトル。結果を変更した後に `setPosition()` を呼ぶ必要がある |
|
|
35
|
-
| `rect.position`、`vertex.color` | 親の値のメンバービュー。書き込みは親の値を直接変更する |
|
|
36
|
-
| `image.pixels` | 現在の画像メモリへの書き込み可能な RGBA ビュー |
|
|
37
|
-
| `target.getTexture()` | RenderTexture の安定した読み取り専用テクスチャビュー |
|
|
38
|
-
| `vertexArray.getVertex(i)` | 現在の頂点ストレージのメンバー。構造が変わった後は再取得する |
|
|
39
|
-
| `soundBuffer.getSamples()` | PCM のメモリ割り当てを維持する読み取り専用の型付きビュー。空のバッファでは `undefined` |
|
|
40
|
-
|
|
41
|
-
Image の再読み込みや resize が成功した後も、古いピクセルビューは古いメモリ割り当てを維持し、新しい画像へ自動的に切り替わることはありません。VertexArray の容量拡張後も、古いメンバーは古いストレージを指します。一方、容量の範囲内で縮小してから再び拡大すると、スロットが再利用される場合があります。
|
|
42
|
-
|
|
43
|
-
`ReadonlyValue`、`ReadonlyPixels`、`ReadonlySamples` などの制約は主に TypeScript で表現されています。すべての読み取り専用型が実行時に凍結されているとは考えないでください。読み取り専用データを変更する場合は先にコピーし、基盤となる共有 buffer を転送、切り離し、リサイズしないでください。
|
|
44
|
-
|
|
45
|
-
## リソースの読み込みと Promise
|
|
46
|
-
|
|
47
|
-
画像とテクスチャには `loadFromFile/Memory/Stream()`、フォントと音楽には `openFromFile/Memory/Stream()` を使います。これらの入口は Promise を返します。
|
|
48
|
-
|
|
49
|
-
```typescript
|
|
50
|
-
import { Texture } from 'sfml.js';
|
|
51
|
-
|
|
52
|
-
const texture = new Texture();
|
|
53
|
-
if (!await texture.loadFromFile('sprite.png')) {
|
|
54
|
-
throw new Error('Cannot decode sprite.png');
|
|
55
|
-
}
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
Image/Texture のファイル読み取りとデコードはバックグラウンドで実行されます。ただし、テクスチャの最終的な GPU アップロードは呼び出し元のスレッドで同期的に行われます。`new Texture(image)`、ピクセルのアップロード、GPU からの読み戻しは同期操作です。非同期読み込みが失敗した場合は通常、以前のリソースが保持されます。通常の SFML の失敗は `false` または `undefined` を返します。
|
|
59
|
-
|
|
60
|
-
同じ画像やテクスチャに対する複数の非同期読み込みは、完了した順に結果を反映します。上書き順序を確定したい場合は、開始順に頼らず、1 件ずつ `await` してください。
|
|
61
|
-
|
|
62
|
-
入力メモリの所有権はモジュールによって異なります。
|
|
63
|
-
|
|
64
|
-
| 入力 | 呼び出し側の責任 |
|
|
65
|
-
| --- | --- |
|
|
66
|
-
| Image/Texture のエンコード済みバイト列 | 呼び出し時にスナップショットを作成するため、その後は元の入力を変更できる |
|
|
67
|
-
| `MemoryInputStream` | 元のバイト列への参照を保持する。読み込み中は内容を変更せず、カーソルを専有する |
|
|
68
|
-
| Audio の非同期読み書き | Promise が完了するまで関連するバッファを変更しない |
|
|
69
|
-
| `Music.openFromMemory()` | 閉じるか再度開くまで入力を変更しない |
|
|
70
|
-
|
|
71
|
-
ストリームとオーディオオブジェクトの具体的な契約は [System](system.ja.md#input-streams) と [Audio](audio.ja.md) を参照してください。
|
|
72
|
-
|
|
73
|
-
<a id="draw-snapshots"></a>
|
|
74
|
-
## 描画スナップショット
|
|
75
|
-
|
|
76
|
-
`target.draw()` は呼び出し時点のプロパティと状態を記録します。元のオブジェクトを変更してから再度描画すると、別のスナップショットが作成されます。
|
|
77
|
-
|
|
78
|
-
```typescript
|
|
79
|
-
import {
|
|
80
|
-
Color, Image, RenderTexture, Sprite, Texture, Vector2f, Vector2u,
|
|
81
|
-
} from 'sfml.js';
|
|
82
|
-
|
|
83
|
-
const target = new RenderTexture(new Vector2u(64, 32));
|
|
84
|
-
const sprite = new Sprite(new Texture(
|
|
85
|
-
new Image(new Vector2u(16, 16), Color.White),
|
|
86
|
-
));
|
|
87
|
-
|
|
88
|
-
target.clear();
|
|
89
|
-
sprite.setPosition(new Vector2f(0, 0));
|
|
90
|
-
target.draw(sprite);
|
|
91
|
-
sprite.setPosition(new Vector2f(32, 0));
|
|
92
|
-
target.draw(sprite);
|
|
93
|
-
target.display();
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
最終的な画像には 2 つの四角形が含まれます。Sprite のプロパティ、RenderStates、頂点データ、必要なリソース参照は記録時に保存されます。その後、テクスチャのピクセル、ジオメトリ、Shader の uniform を変更する際は、バインディングが古い状態に依存するコマンドを先に送信します。
|
|
97
|
-
|
|
98
|
-
| 操作 | 意味 |
|
|
99
|
-
| --- | --- |
|
|
100
|
-
| `clear()`、`draw()`、`setView()` | コマンドを順番に記録する。キューが満杯になると、途中で送信される場合がある |
|
|
101
|
-
| `flush()` | 記録済みのコマンドを同期的に送信する |
|
|
102
|
-
| `RenderWindow.display()` | コマンドを送信し、ウィンドウのバッファを交換する |
|
|
103
|
-
| `RenderTexture.display()` | コマンドを送信し、サンプリング可能なテクスチャを更新する |
|
|
104
|
-
|
|
105
|
-
`flush()` はオフスクリーンターゲットの `display()` の代わりにはなりません。RenderTexture の新しい内容を使う前に display を呼んでください。自身のテクスチャを直接サンプリングしたり、未送信のターゲット間に循環依存を作ったりすると拒否されます。
|
|
106
|
-
|
|
107
|
-
バッチ処理は JS/C++ 境界の呼び出しを減らしますが、複数の Sprite を自動的に 1 回の GPU 描画にまとめるわけではありません。同じテクスチャを共有する大量のジオメトリは VertexArray で構成でき、静的なジオメトリには VertexBuffer を利用できます。
|
|
108
|
-
|
|
109
|
-
## Node.js のイベントループ
|
|
110
|
-
|
|
111
|
-
ウィンドウ操作はメインスレッドで実行します。フレームごとに `pollEvent()` または `handleEvents()` を使い、`setImmediate()` で次のフレームを予約します。
|
|
112
|
-
|
|
113
|
-
`waitEvent()` は SFML の同期的な待機セマンティクスを維持しています。`sleep()` は Node のタイマーを使って Promise を返すため、待機中もイベントループは動き続けます。`display()` は同期メソッドであり、フレームレート制限、垂直同期、ドライバーの処理の影響を受ける場合があります。
|
|
114
|
-
|
|
115
|
-
ネットワーク I/O は Promise を返します。`socket.setBlocking(true)` は Promise が操作可能になるまで待機することを意味し、Node のスレッド全体を同期的にブロックするものではありません。
|
|
116
|
-
|
|
117
|
-
Audio Worker は容量を制限した共有 PCM スロットを使います。コールバックのビューは、そのコールバックが完了するまでしか有効ではありません。バックグラウンドの Worker だけではプロセスを存続させないため、再生中はウィンドウループを維持するか、明示的に待機してください。
|
|
118
|
-
|
|
119
|
-
## エラーとクリーンアップ
|
|
120
|
-
|
|
121
|
-
| 結果 | 対処 |
|
|
122
|
-
| --- | --- |
|
|
123
|
-
| `false`/`undefined`、SocketStatus、プロトコルのレスポンス | 戻されたステータスを確認する |
|
|
124
|
-
| `TypeError`/`RangeError` | 引数の型や範囲を修正する |
|
|
125
|
-
| `SFMLError` | バインディングや基盤リソースの実行時エラーに対処する |
|
|
126
|
-
| ユーザーコールバックが投げた例外 | 元のエラーオブジェクトがそのまま伝播する |
|
|
127
|
-
|
|
128
|
-
SFML の診断は既定で stderr に出力され、`setErrorOutput()` で出力先を変更できます。ログは戻り値の確認の代わりにはなりません。
|
|
129
|
-
|
|
130
|
-
ウィンドウには `close()`、ネットワークオブジェクトにはそれぞれの終了インターフェースを使います。ファイルストリームとオーディオ Worker の非同期クリーンアップには `await` が必要です。ガベージコレクションだけに頼っても、ファイルへの書き込み完了、接続の速やかな終了、録音キューの排出は保証されません。リソースの終了方法は、対応するモジュールのドキュメントを参照してください。
|
package/docs/concepts.ko.md
DELETED
|
@@ -1,130 +0,0 @@
|
|
|
1
|
-
# 핵심 개념
|
|
2
|
-
|
|
3
|
-
[English](concepts.md) / [简体中文](concepts.zh-CN.md) / [日本語](concepts.ja.md) / **한국어**
|
|
4
|
-
|
|
5
|
-
> sfml.js를 사용할 때는 먼저 값, 리소스, 뷰를 구분하고, 이어서 명령 기록, 제출, 화면 표시를 구분하세요. 이러한 경계가 복사, 비동기 로딩, 그리기 동작을 결정합니다.
|
|
6
|
-
|
|
7
|
-
[문서 홈](README.ko.md) · [API 안내](api.ko.md)
|
|
8
|
-
|
|
9
|
-
## 값, 리소스, 뷰
|
|
10
|
-
|
|
11
|
-
벡터, 각도, 색상, 사각형, 정점, 행렬 등의 값 타입은 처음에 JS TypedArray에 저장됩니다. 수학 연산은 JavaScript에서 수행하며, 네이티브 핸들이 필요할 때에만 같은 메모리를 감쌉니다. `Time`은 마이크로초 단위의 `bigint`를 사용합니다.
|
|
12
|
-
|
|
13
|
-
Texture, Image, Sprite, Text, 오디오 객체 등의 리소스는 네이티브 측에서 관리합니다. JS 래퍼 객체와 살아 있는 뷰가 함께 관련 메모리 할당의 수명을 유지합니다. 리소스 해제는 소유 스레드와 하위 의존성의 수명 주기를 따릅니다.
|
|
14
|
-
|
|
15
|
-
```typescript
|
|
16
|
-
import { FloatRect, Vector2f } from 'sfml.js';
|
|
17
|
-
|
|
18
|
-
const rect = new FloatRect(new Vector2f(10, 20), new Vector2f(100, 80));
|
|
19
|
-
const member = rect.position;
|
|
20
|
-
member.x = 30; // 멤버 뷰이므로 rect를 수정합니다.
|
|
21
|
-
|
|
22
|
-
const copy = new Vector2f(member);
|
|
23
|
-
copy.x = 90; // 독립 복사본이므로 rect에 영향을 주지 않습니다.
|
|
24
|
-
|
|
25
|
-
rect.position = new Vector2f(5, 6); // 값으로 복사하며, member는 여전히 rect의 멤버를 가리킵니다.
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
일반적인 JS 대입은 여전히 참조 대입입니다. 독립적인 값이 필요하면 복사 생성자를 사용하세요. 리소스의 복사 규칙은 클래스마다 다릅니다. 예를 들어 `new Texture(texture)`는 GPU 내용을 복사하지만, `new Sprite(sprite)`는 스프라이트 속성만 복사하고 텍스처를 공유합니다.
|
|
29
|
-
|
|
30
|
-
`get...()`이라는 이름만으로 반환값이 독립적인지 판단하지 마세요.
|
|
31
|
-
|
|
32
|
-
| 읽기 방식 | 소유권 및 업데이트 동작 |
|
|
33
|
-
| --- | --- |
|
|
34
|
-
| `sprite.getPosition()` | 독립적인 벡터. 결과를 수정한 뒤 `setPosition()`을 호출해야 함 |
|
|
35
|
-
| `rect.position`, `vertex.color` | 부모 값의 멤버 뷰. 쓰면 부모 값이 직접 수정됨 |
|
|
36
|
-
| `image.pixels` | 현재 이미지 할당에 대한 쓰기 가능한 RGBA 뷰 |
|
|
37
|
-
| `target.getTexture()` | RenderTexture의 안정적인 읽기 전용 텍스처 뷰 |
|
|
38
|
-
| `vertexArray.getVertex(i)` | 현재 정점 저장소의 멤버. 구조가 바뀌면 다시 가져와야 함 |
|
|
39
|
-
| `soundBuffer.getSamples()` | PCM 할당의 수명을 유지하는 읽기 전용 타입 뷰. 빈 버퍼는 `undefined` |
|
|
40
|
-
|
|
41
|
-
Image를 다시 로드하거나 resize한 뒤에도 기존 픽셀 뷰는 이전 할당의 수명을 계속 유지하며, 새 이미지로 자동 전환되지 않습니다. VertexArray의 용량이 늘어난 뒤에도 이전 멤버는 이전 저장소를 가리킵니다. 용량 내에서 크기를 줄였다가 다시 늘리는 경우에는 슬롯이 재사용될 수 있습니다.
|
|
42
|
-
|
|
43
|
-
`ReadonlyValue`, `ReadonlyPixels`, `ReadonlySamples` 등의 제약은 주로 TypeScript로 표현됩니다. 모든 읽기 전용 타입이 런타임에서 동결된다고 해석해서는 안 됩니다. 읽기 전용 데이터를 수정하려면 먼저 복사하세요. 기반 공유 buffer를 전송하거나 분리하거나 크기를 바꾸지 마세요.
|
|
44
|
-
|
|
45
|
-
## 리소스 로딩과 Promise
|
|
46
|
-
|
|
47
|
-
이미지와 텍스처는 `loadFromFile/Memory/Stream()`을, 폰트와 음악은 `openFromFile/Memory/Stream()`을 사용합니다. 이 진입점들은 Promise를 반환합니다.
|
|
48
|
-
|
|
49
|
-
```typescript
|
|
50
|
-
import { Texture } from 'sfml.js';
|
|
51
|
-
|
|
52
|
-
const texture = new Texture();
|
|
53
|
-
if (!await texture.loadFromFile('sprite.png')) {
|
|
54
|
-
throw new Error('Cannot decode sprite.png');
|
|
55
|
-
}
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
Image/Texture의 파일 읽기와 디코딩은 백그라운드에서 수행되지만, 텍스처의 최종 GPU 업로드는 호출 스레드에서 동기식으로 완료됩니다. `new Texture(image)`, 픽셀 업로드, GPU 읽어오기는 동기식 작업입니다. 비동기 로딩 실패 시에는 보통 기존 리소스를 유지하며, 일반적인 SFML 실패는 `false`나 `undefined`를 반환합니다.
|
|
59
|
-
|
|
60
|
-
같은 이미지나 텍스처에 대한 여러 비동기 로딩은 완료 순서대로 결과를 반영합니다. 덮어쓰기 순서를 확정해야 한다면 하나씩 `await`하세요. 시작 순서에 의존해서는 안 됩니다.
|
|
61
|
-
|
|
62
|
-
입력 메모리의 소유권은 모듈마다 다릅니다.
|
|
63
|
-
|
|
64
|
-
| 입력 | 호출자의 책임 |
|
|
65
|
-
| --- | --- |
|
|
66
|
-
| Image/Texture의 인코딩된 바이트 | 호출 시 스냅샷을 만들므로 이후 원본 입력을 수정해도 됨 |
|
|
67
|
-
| `MemoryInputStream` | 원본 바이트 참조를 유지하므로 로딩 중 내용을 변경하지 않고 커서를 독점 사용 |
|
|
68
|
-
| Audio 비동기 읽기/쓰기 | Promise가 완료될 때까지 관련 버퍼를 변경하지 않음 |
|
|
69
|
-
| `Music.openFromMemory()` | 닫거나 다시 열 때까지 입력을 변경하지 않음 |
|
|
70
|
-
|
|
71
|
-
스트림과 오디오 객체의 구체적인 계약은 [System](system.ko.md#input-streams)과 [Audio](audio.ko.md)를 참고하세요.
|
|
72
|
-
|
|
73
|
-
<a id="draw-snapshots"></a>
|
|
74
|
-
## 그리기 스냅샷
|
|
75
|
-
|
|
76
|
-
`target.draw()`는 호출 시점의 속성과 상태를 기록합니다. 원본 객체를 수정한 뒤 다시 그리면 별도의 스냅샷이 만들어집니다.
|
|
77
|
-
|
|
78
|
-
```typescript
|
|
79
|
-
import {
|
|
80
|
-
Color, Image, RenderTexture, Sprite, Texture, Vector2f, Vector2u,
|
|
81
|
-
} from 'sfml.js';
|
|
82
|
-
|
|
83
|
-
const target = new RenderTexture(new Vector2u(64, 32));
|
|
84
|
-
const sprite = new Sprite(new Texture(
|
|
85
|
-
new Image(new Vector2u(16, 16), Color.White),
|
|
86
|
-
));
|
|
87
|
-
|
|
88
|
-
target.clear();
|
|
89
|
-
sprite.setPosition(new Vector2f(0, 0));
|
|
90
|
-
target.draw(sprite);
|
|
91
|
-
sprite.setPosition(new Vector2f(32, 0));
|
|
92
|
-
target.draw(sprite);
|
|
93
|
-
target.display();
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
최종 화면에는 사각형 두 개가 포함됩니다. Sprite 속성, RenderStates, 정점 데이터, 필요한 리소스 참조는 기록 시점에 저장됩니다. 이후 텍스처 픽셀, 지오메트리, Shader uniform을 변경하면 바인딩은 이전 상태에 의존하는 명령을 먼저 제출합니다.
|
|
97
|
-
|
|
98
|
-
| 작업 | 의미 |
|
|
99
|
-
| --- | --- |
|
|
100
|
-
| `clear()`, `draw()`, `setView()` | 명령을 순서대로 기록. 큐가 가득 차면 미리 제출할 수 있음 |
|
|
101
|
-
| `flush()` | 기존 명령을 동기식으로 제출 |
|
|
102
|
-
| `RenderWindow.display()` | 명령 제출 후 창 버퍼 교환 |
|
|
103
|
-
| `RenderTexture.display()` | 명령 제출 후 샘플링 가능한 텍스처 업데이트 |
|
|
104
|
-
|
|
105
|
-
`flush()`는 오프스크린 대상의 `display()`를 대체할 수 없습니다. RenderTexture의 새 내용을 사용하기 전에 display를 호출하세요. 자신의 텍스처를 직접 샘플링하거나 아직 제출되지 않은 대상 사이에 순환 의존성을 만드는 작업은 거부됩니다.
|
|
106
|
-
|
|
107
|
-
일괄 처리는 JS/C++ 경계를 넘는 호출을 줄이지만, 여러 Sprite를 자동으로 하나의 GPU 그리기 호출로 합치지는 않습니다. 텍스처를 공유하는 지오메트리가 많다면 VertexArray로 구성할 수 있고, 정적 지오메트리에는 VertexBuffer를 사용할 수 있습니다.
|
|
108
|
-
|
|
109
|
-
## Node.js 이벤트 루프
|
|
110
|
-
|
|
111
|
-
창 작업은 메인 스레드에서 실행합니다. 매 프레임 `pollEvent()`나 `handleEvents()`를 사용하고, `setImmediate()`로 다음 프레임을 예약하세요.
|
|
112
|
-
|
|
113
|
-
`waitEvent()`는 SFML의 동기식 대기 의미를 유지합니다. `sleep()`은 Node 타이머를 사용하고 Promise를 반환하며, 대기 중에도 이벤트 루프가 계속 실행됩니다. `display()`는 동기식 메서드로, 프레임 제한, 수직 동기화, 드라이버 작업의 영향을 받을 수 있습니다.
|
|
114
|
-
|
|
115
|
-
네트워크 I/O는 Promise를 반환합니다. `socket.setBlocking(true)`는 작업이 준비될 때까지 Promise가 기다린다는 뜻이며, Node 스레드 전체를 동기식으로 차단하지 않습니다.
|
|
116
|
-
|
|
117
|
-
Audio Worker는 크기가 제한된 공유 PCM 슬롯을 사용하며, 콜백 뷰는 해당 콜백이 완료되기 전까지만 유효합니다. 백그라운드 Worker만으로는 프로세스가 계속 실행되지 않으므로, 재생 중에는 창 루프를 유지하거나 명시적으로 기다리세요.
|
|
118
|
-
|
|
119
|
-
## 오류와 정리
|
|
120
|
-
|
|
121
|
-
| 결과 | 처리 방법 |
|
|
122
|
-
| --- | --- |
|
|
123
|
-
| `false`/`undefined`, SocketStatus, 프로토콜 응답 | 반환 상태 확인 |
|
|
124
|
-
| `TypeError`/`RangeError` | 매개변수 타입이나 범위 수정 |
|
|
125
|
-
| `SFMLError` | 바인딩 또는 하위 리소스의 실행 실패 처리 |
|
|
126
|
-
| 사용자 콜백의 예외 | 원본 오류 객체가 계속 전파됨 |
|
|
127
|
-
|
|
128
|
-
SFML 진단은 기본적으로 stderr에 기록되며, `setErrorOutput()`으로 경로를 바꿀 수 있습니다. 로그가 반환값 확인을 대신하지는 않습니다.
|
|
129
|
-
|
|
130
|
-
창은 `close()`로, 네트워크 객체는 각각의 닫기 인터페이스로 정리하며, 파일 스트림과 오디오 Worker의 비동기 정리에는 `await`가 필요합니다. 가비지 컬렉션에만 의존하면 파일 쓰기 완료, 적시 연결 종료, 녹음 큐 비우기를 보장할 수 없습니다. 리소스를 닫는 방법은 해당 모듈 문서를 참고하세요.
|
package/docs/concepts.md
DELETED
|
@@ -1,131 +0,0 @@
|
|
|
1
|
-
# Core Concepts
|
|
2
|
-
|
|
3
|
-
**English** · [简体中文](concepts.zh-CN.md) · [日本語](concepts.ja.md) · [한국어](concepts.ko.md)
|
|
4
|
-
|
|
5
|
-
> When using sfml.js, distinguish values, resources and views, then distinguish command recording, submission and presentation. These boundaries determine copying, asynchronous loading and drawing behavior.
|
|
6
|
-
|
|
7
|
-
[Documentation](README.md) · [API guide](api.md)
|
|
8
|
-
|
|
9
|
-
## Values, resources and views
|
|
10
|
-
|
|
11
|
-
Value types such as vectors, angles, colors, rectangles, vertices and matrices start with JS TypedArray storage. Calculations run in JavaScript; a native handle wraps the same memory only when needed. `Time` uses a microsecond `bigint`.
|
|
12
|
-
|
|
13
|
-
Resources such as Texture, Image, Sprite, Text and audio objects are managed natively. JS wrappers and live views keep their allocations alive; resource release follows the owning thread and the lifetime of underlying dependencies.
|
|
14
|
-
|
|
15
|
-
```typescript
|
|
16
|
-
import { FloatRect, Vector2f } from 'sfml.js';
|
|
17
|
-
|
|
18
|
-
const rect = new FloatRect(new Vector2f(10, 20), new Vector2f(100, 80));
|
|
19
|
-
const member = rect.position;
|
|
20
|
-
member.x = 30; // A member view: modifies rect.
|
|
21
|
-
|
|
22
|
-
const copy = new Vector2f(member);
|
|
23
|
-
copy.x = 90; // An independent copy: does not affect rect.
|
|
24
|
-
|
|
25
|
-
rect.position = new Vector2f(5, 6); // Copies by value; member still refers to rect's member.
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
Ordinary JS assignment still assigns a reference. Use a copy constructor for an independent value. Resource copying rules vary by class: for example, `new Texture(texture)` copies GPU contents, while `new Sprite(sprite)` copies sprite properties but shares the texture.
|
|
29
|
-
|
|
30
|
-
Do not assume a return value is independent just because the method is named `get...()`:
|
|
31
|
-
|
|
32
|
-
| Access | Ownership and update behavior |
|
|
33
|
-
| --- | --- |
|
|
34
|
-
| `sprite.getPosition()` | Independent vector; call `setPosition()` after modifying the result |
|
|
35
|
-
| `rect.position`, `vertex.color` | Member views of the parent value; writes directly modify the parent |
|
|
36
|
-
| `image.pixels` | Writable RGBA view of the current image allocation |
|
|
37
|
-
| `target.getTexture()` | Stable read-only texture view of a RenderTexture |
|
|
38
|
-
| `vertexArray.getVertex(i)` | Member of current vertex storage; reacquire after structural changes |
|
|
39
|
-
| `soundBuffer.getSamples()` | Read-only typed view that keeps the PCM allocation alive; `undefined` for an empty buffer |
|
|
40
|
-
|
|
41
|
-
After an Image is successfully reloaded or resized, old pixel views keep the old allocation alive; they do not automatically switch to the new image. Old VertexArray members also refer to old storage after capacity growth; shrinking and expanding within capacity may reuse slots.
|
|
42
|
-
|
|
43
|
-
Constraints such as `ReadonlyValue`, `ReadonlyPixels` and `ReadonlySamples` are primarily expressed through TypeScript; not every read-only type is frozen at runtime. Copy read-only data before modifying it, and do not transfer, detach or resize the underlying shared buffer.
|
|
44
|
-
|
|
45
|
-
## Resource loading and promises
|
|
46
|
-
|
|
47
|
-
Use `loadFromFile/Memory/Stream()` for images and textures, and `openFromFile/Memory/Stream()` for fonts and music. These methods return promises:
|
|
48
|
-
|
|
49
|
-
```typescript
|
|
50
|
-
import { Texture } from 'sfml.js';
|
|
51
|
-
|
|
52
|
-
const texture = new Texture();
|
|
53
|
-
if (!await texture.loadFromFile('sprite.png')) {
|
|
54
|
-
throw new Error('Cannot decode sprite.png');
|
|
55
|
-
}
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
Image/Texture file reading and decoding run in the background; the final texture upload to the GPU is still synchronous on the calling thread. `new Texture(image)`, pixel uploads and GPU readback are synchronous. Failed asynchronous loads generally preserve the old resource; ordinary SFML failures return `false` or `undefined`.
|
|
59
|
-
|
|
60
|
-
Multiple asynchronous loads on the same image or texture publish results in completion order. Use sequential `await` calls when you need a deterministic replacement order; do not rely on the order in which loads were started.
|
|
61
|
-
|
|
62
|
-
Input memory ownership varies by module:
|
|
63
|
-
|
|
64
|
-
| Input | Caller responsibility |
|
|
65
|
-
| --- | --- |
|
|
66
|
-
| Encoded bytes for Image/Texture | Snapshotted at call time; the original input may be modified afterward |
|
|
67
|
-
| `MemoryInputStream` | Retains a reference to the original bytes; keep contents unchanged during loading and give the operation exclusive cursor access |
|
|
68
|
-
| Asynchronous Audio reads/writes | Keep the relevant buffers unchanged until the promise completes |
|
|
69
|
-
| `Music.openFromMemory()` | Keep input unchanged until closing or reopening |
|
|
70
|
-
|
|
71
|
-
See [System](system.md#input-streams) and [Audio](audio.md) for the specific stream and audio contracts.
|
|
72
|
-
|
|
73
|
-
<a id="draw-snapshots"></a>
|
|
74
|
-
|
|
75
|
-
## Draw snapshots
|
|
76
|
-
|
|
77
|
-
`target.draw()` records properties and state at call time. Modifying the original object and drawing again creates another snapshot:
|
|
78
|
-
|
|
79
|
-
```typescript
|
|
80
|
-
import {
|
|
81
|
-
Color, Image, RenderTexture, Sprite, Texture, Vector2f, Vector2u,
|
|
82
|
-
} from 'sfml.js';
|
|
83
|
-
|
|
84
|
-
const target = new RenderTexture(new Vector2u(64, 32));
|
|
85
|
-
const sprite = new Sprite(new Texture(
|
|
86
|
-
new Image(new Vector2u(16, 16), Color.White),
|
|
87
|
-
));
|
|
88
|
-
|
|
89
|
-
target.clear();
|
|
90
|
-
sprite.setPosition(new Vector2f(0, 0));
|
|
91
|
-
target.draw(sprite);
|
|
92
|
-
sprite.setPosition(new Vector2f(32, 0));
|
|
93
|
-
target.draw(sprite);
|
|
94
|
-
target.display();
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
The final image contains two squares. Sprite properties, RenderStates, vertex data and required resource references are saved during recording. Before a subsequent change to texture pixels, geometry or shader uniforms, the binding submits commands that depend on the old state.
|
|
98
|
-
|
|
99
|
-
| Operation | Meaning |
|
|
100
|
-
| --- | --- |
|
|
101
|
-
| `clear()`, `draw()`, `setView()` | Record commands in order; a full queue may trigger early submission |
|
|
102
|
-
| `flush()` | Synchronously submit existing commands |
|
|
103
|
-
| `RenderWindow.display()` | Submit and swap window buffers |
|
|
104
|
-
| `RenderTexture.display()` | Submit and update the texture available for sampling |
|
|
105
|
-
|
|
106
|
-
`flush()` does not replace `display()` on an off-screen target. Call display before using new RenderTexture contents; sampling its own texture directly or creating cyclic dependencies between unsubmitted targets is rejected.
|
|
107
|
-
|
|
108
|
-
Batching reduces calls across the JS/C++ boundary; it does not automatically combine multiple sprites into one GPU draw. Organize large amounts of geometry sharing a texture into a VertexArray; use VertexBuffer for static geometry.
|
|
109
|
-
|
|
110
|
-
## Node.js event loop
|
|
111
|
-
|
|
112
|
-
Window operations run on the main thread. Use `pollEvent()` or `handleEvents()` each frame, and schedule the next frame with `setImmediate()`.
|
|
113
|
-
|
|
114
|
-
`waitEvent()` preserves SFML's synchronous waiting semantics. `sleep()` uses a Node timer and returns a promise; the event loop continues running while it waits. `display()` is synchronous and may be affected by frame limits, vertical sync and driver work.
|
|
115
|
-
|
|
116
|
-
Network I/O returns promises. `socket.setBlocking(true)` means the promise waits for the operation to become ready; it does not synchronously block the entire Node thread.
|
|
117
|
-
|
|
118
|
-
Audio Workers use bounded shared PCM slots, and callback views are valid only until that callback completes. Background Workers do not keep the process alive on their own; maintain a window loop or explicitly wait during playback.
|
|
119
|
-
|
|
120
|
-
## Errors and cleanup
|
|
121
|
-
|
|
122
|
-
| Result | Handling |
|
|
123
|
-
| --- | --- |
|
|
124
|
-
| `false`/`undefined`, SocketStatus, protocol responses | Check the returned status |
|
|
125
|
-
| `TypeError`/`RangeError` | Correct the argument type or range |
|
|
126
|
-
| `SFMLError` | Handle binding or underlying resource failures |
|
|
127
|
-
| Error thrown by a user callback | The original error object propagates |
|
|
128
|
-
|
|
129
|
-
SFML diagnostics go to stderr by default and can be routed with `setErrorOutput()`. Logging is not a substitute for checking return values.
|
|
130
|
-
|
|
131
|
-
Use `close()` for windows and each network object's shutdown API. Use `await` for asynchronous cleanup of file streams and audio Workers. Relying solely on garbage collection cannot guarantee completed file writes, timely connection shutdown or drained recording queues. See the relevant module guide for resource shutdown methods.
|