sfml.js 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (313) hide show
  1. package/README.ja.md +10 -9
  2. package/README.ko.md +10 -9
  3. package/README.md +10 -9
  4. package/README.zh-CN.md +10 -9
  5. package/binding.gyp +23 -16
  6. package/dist/audio/effect-processor.js +9 -3
  7. package/dist/audio/input-sound-file.js +41 -15
  8. package/dist/audio/listener.js +33 -11
  9. package/dist/audio/music.js +41 -18
  10. package/dist/audio/output-sound-file.js +4 -2
  11. package/dist/audio/playback-device.js +11 -3
  12. package/dist/audio/sound-buffer-recorder.js +8 -5
  13. package/dist/audio/sound-buffer.js +40 -17
  14. package/dist/audio/sound-file-factory.js +21 -9
  15. package/dist/audio/sound-file-reader.js +21 -7
  16. package/dist/audio/sound-recorder.js +36 -15
  17. package/dist/audio/sound-source.js +117 -40
  18. package/dist/audio/sound-stream.js +14 -5
  19. package/dist/audio/sound.js +9 -4
  20. package/dist/audio/value.js +42 -16
  21. package/dist/graphics/blend-mode.js +2 -1
  22. package/dist/graphics/boolean-vector.d.ts +1 -2
  23. package/dist/graphics/boolean-vector.js +19 -9
  24. package/dist/graphics/color.js +2 -1
  25. package/dist/graphics/convex-shape.js +7 -3
  26. package/dist/graphics/font.js +52 -23
  27. package/dist/graphics/glsl-matrix.js +8 -3
  28. package/dist/graphics/glsl.js +47 -16
  29. package/dist/graphics/glyph.js +27 -10
  30. package/dist/graphics/image.js +30 -14
  31. package/dist/graphics/rect.js +15 -8
  32. package/dist/graphics/render-states.js +18 -9
  33. package/dist/graphics/render-target.js +49 -23
  34. package/dist/graphics/render-texture.js +24 -12
  35. package/dist/graphics/render-window.js +6 -3
  36. package/dist/graphics/shader.js +67 -32
  37. package/dist/graphics/shape.js +25 -13
  38. package/dist/graphics/sprite.js +19 -9
  39. package/dist/graphics/stencil-mode.js +10 -6
  40. package/dist/graphics/swap.js +2 -1
  41. package/dist/graphics/text.js +123 -48
  42. package/dist/graphics/texture.js +48 -24
  43. package/dist/graphics/transform.js +29 -13
  44. package/dist/graphics/transformable.js +2 -1
  45. package/dist/graphics/vertex-array.js +40 -18
  46. package/dist/graphics/vertex-buffer.js +39 -19
  47. package/dist/graphics/vertex.js +6 -3
  48. package/dist/graphics/view.js +30 -14
  49. package/dist/index.d.ts +4 -4
  50. package/dist/internal/audio-codec-registry.js +12 -6
  51. package/dist/internal/audio-input-stream.js +2 -1
  52. package/dist/internal/audio-music-pump.js +58 -24
  53. package/dist/internal/audio-recorder-session.js +17 -7
  54. package/dist/internal/audio-worker-session.js +28 -10
  55. package/dist/internal/audio-worker.js +40 -21
  56. package/dist/internal/glsl-value.d.ts +3 -1
  57. package/dist/internal/glsl-value.js +18 -8
  58. package/dist/internal/graphics-state.js +29 -15
  59. package/dist/internal/input-stream.d.ts +3 -1
  60. package/dist/internal/input-stream.js +16 -7
  61. package/dist/internal/numeric-properties.js +2 -1
  62. package/dist/internal/render-states.js +2 -1
  63. package/dist/internal/scalar.js +22 -13
  64. package/dist/internal/shaped-glyph.d.ts +3 -1
  65. package/dist/internal/shaped-glyph.js +12 -4
  66. package/dist/internal/struct-view.d.ts +3 -1
  67. package/dist/internal/struct-view.js +3 -1
  68. package/dist/internal/transformable.js +2 -1
  69. package/dist/network/common.js +23 -11
  70. package/dist/network/dns.js +25 -17
  71. package/dist/network/ftp.js +43 -18
  72. package/dist/network/http.js +126 -56
  73. package/dist/network/ip-address.js +50 -25
  74. package/dist/network/packet.js +63 -25
  75. package/dist/network/sftp.js +175 -74
  76. package/dist/network/socket-selector.js +28 -14
  77. package/dist/network/socket.js +71 -30
  78. package/dist/network/tcp-listener.js +42 -19
  79. package/dist/network/tcp-socket.js +111 -53
  80. package/dist/network/tls-material.js +2 -1
  81. package/dist/network/udp-socket.js +68 -33
  82. package/dist/system/angle.js +2 -1
  83. package/dist/system/clock.js +4 -2
  84. package/dist/system/err.js +5 -2
  85. package/dist/system/file-input-stream.js +8 -4
  86. package/dist/system/input-stream.js +6 -3
  87. package/dist/system/operators.d.ts +1 -1
  88. package/dist/system/operators.js +90 -50
  89. package/dist/system/sleep.js +4 -2
  90. package/dist/system/time.js +12 -6
  91. package/dist/system/vector2.js +6 -7
  92. package/dist/system/vector3.js +11 -6
  93. package/dist/window/clipboard.js +2 -1
  94. package/dist/window/context.js +10 -5
  95. package/dist/window/cursor.js +2 -1
  96. package/dist/window/event.js +9 -5
  97. package/dist/window/mouse.js +4 -2
  98. package/dist/window/video-mode.js +2 -1
  99. package/dist/window/window.js +19 -12
  100. package/native/addon.cc +25 -12
  101. package/native/audio-binding.cc +266 -126
  102. package/native/audio-codec-binding.cc +147 -77
  103. package/native/audio-device-binding.cc +76 -49
  104. package/native/audio-file-binding.cc +116 -67
  105. package/native/audio-recorder-binding.cc +147 -98
  106. package/native/audio-recorder.h +1 -1
  107. package/native/audio-state.h +53 -30
  108. package/native/audio-stream-binding.cc +148 -94
  109. package/native/audio-stream.h +5 -4
  110. package/native/audio-worker-binding.cc +163 -81
  111. package/native/audio-worker.h +35 -19
  112. package/native/batch-drawable.cc +29 -16
  113. package/native/batch-drawable.h +11 -8
  114. package/native/context-binding.cc +40 -27
  115. package/native/context-settings.h +15 -8
  116. package/native/deferred-delete.cc +9 -6
  117. package/native/deferred-delete.h +7 -8
  118. package/native/error-stream-binding.cc +42 -28
  119. package/native/font-binding.cc +89 -48
  120. package/native/graphics-binding.cc +122 -72
  121. package/native/graphics-state.h +50 -36
  122. package/native/image-binding.cc +38 -24
  123. package/native/image-state.h +26 -18
  124. package/native/input-binding.cc +42 -27
  125. package/native/render-window-binding.cc +38 -23
  126. package/native/shader-binding.cc +115 -50
  127. package/native/shape-binding.cc +94 -49
  128. package/native/shape-state.h +18 -9
  129. package/native/shaped-glyph-storage.h +9 -5
  130. package/native/stream-binding.cc +143 -117
  131. package/native/system-binding.cc +17 -12
  132. package/native/text-binding.cc +68 -35
  133. package/native/text-state.h +25 -18
  134. package/native/texture-binding.cc +42 -33
  135. package/native/texture-resource.h +20 -12
  136. package/native/time-value.h +3 -1
  137. package/native/transformable-binding.cc +12 -6
  138. package/native/transformable-state.h +6 -6
  139. package/native/value-binding.h +46 -28
  140. package/native/value-layout.h +10 -10
  141. package/native/values-binding.cc +29 -23
  142. package/native/vertex-binding.cc +18 -12
  143. package/native/vertex-buffer-binding.cc +38 -24
  144. package/native/vertex-storage.h +2 -2
  145. package/native/view-data.h +4 -3
  146. package/native/window-binding.cc +75 -45
  147. package/native/window-event.h +20 -11
  148. package/native/window-owner.h +15 -12
  149. package/package.json +40 -48
  150. package/src/audio/effect-processor.ts +9 -3
  151. package/src/audio/input-sound-file.ts +108 -36
  152. package/src/audio/listener.ts +39 -13
  153. package/src/audio/music.ts +112 -47
  154. package/src/audio/output-sound-file.ts +40 -11
  155. package/src/audio/playback-device.ts +23 -8
  156. package/src/audio/sound-buffer-recorder.ts +35 -13
  157. package/src/audio/sound-buffer.ts +166 -58
  158. package/src/audio/sound-file-factory.ts +127 -49
  159. package/src/audio/sound-file-reader.ts +49 -15
  160. package/src/audio/sound-recorder.ts +100 -34
  161. package/src/audio/sound-source.ts +142 -45
  162. package/src/audio/sound-stream.ts +15 -5
  163. package/src/audio/sound.ts +12 -4
  164. package/src/audio/value.ts +89 -26
  165. package/src/graphics/blend-mode.ts +3 -1
  166. package/src/graphics/boolean-vector.ts +56 -26
  167. package/src/graphics/color.ts +3 -1
  168. package/src/graphics/convex-shape.ts +10 -3
  169. package/src/graphics/font.ts +171 -50
  170. package/src/graphics/glsl-matrix.ts +9 -3
  171. package/src/graphics/glsl.ts +81 -35
  172. package/src/graphics/glyph.ts +67 -26
  173. package/src/graphics/image.ts +119 -45
  174. package/src/graphics/rect.ts +56 -24
  175. package/src/graphics/render-states.ts +31 -14
  176. package/src/graphics/render-target.ts +197 -81
  177. package/src/graphics/render-texture.ts +36 -12
  178. package/src/graphics/render-window.ts +9 -3
  179. package/src/graphics/shader.ts +186 -61
  180. package/src/graphics/shape.ts +93 -35
  181. package/src/graphics/sprite.ts +64 -25
  182. package/src/graphics/stencil-mode.ts +12 -6
  183. package/src/graphics/swap.ts +3 -2
  184. package/src/graphics/text.ts +229 -74
  185. package/src/graphics/texture.ts +180 -61
  186. package/src/graphics/transform.ts +132 -47
  187. package/src/graphics/transformable.ts +3 -1
  188. package/src/graphics/vertex-array.ts +87 -35
  189. package/src/graphics/vertex-buffer.ts +97 -33
  190. package/src/graphics/vertex.ts +9 -3
  191. package/src/graphics/view.ts +59 -21
  192. package/src/index.ts +101 -23
  193. package/src/internal/audio-codec-registry.ts +18 -6
  194. package/src/internal/audio-input-stream.ts +6 -2
  195. package/src/internal/audio-music-pump.ts +116 -41
  196. package/src/internal/audio-native.ts +249 -96
  197. package/src/internal/audio-recorder-session.ts +68 -24
  198. package/src/internal/audio-worker-session.ts +65 -21
  199. package/src/internal/audio-worker.ts +85 -41
  200. package/src/internal/glsl-value.ts +26 -11
  201. package/src/internal/graphics-state.ts +57 -20
  202. package/src/internal/input-stream.ts +23 -10
  203. package/src/internal/native.ts +252 -99
  204. package/src/internal/numeric-properties.ts +2 -1
  205. package/src/internal/render-states.ts +3 -1
  206. package/src/internal/scalar.ts +33 -14
  207. package/src/internal/shaped-glyph.ts +25 -12
  208. package/src/internal/struct-view.ts +40 -13
  209. package/src/internal/transformable.ts +3 -1
  210. package/src/network/common.ts +35 -11
  211. package/src/network/dns.ts +95 -38
  212. package/src/network/ftp.ts +129 -47
  213. package/src/network/http.ts +232 -77
  214. package/src/network/ip-address.ts +118 -48
  215. package/src/network/packet.ts +161 -54
  216. package/src/network/sftp.ts +498 -168
  217. package/src/network/socket-selector.ts +66 -26
  218. package/src/network/socket.ts +133 -46
  219. package/src/network/tcp-listener.ts +78 -29
  220. package/src/network/tcp-socket.ts +240 -95
  221. package/src/network/tls-material.ts +6 -2
  222. package/src/network/udp-socket.ts +147 -53
  223. package/src/system/angle.ts +3 -1
  224. package/src/system/clock.ts +12 -4
  225. package/src/system/err.ts +5 -2
  226. package/src/system/file-input-stream.ts +12 -4
  227. package/src/system/input-stream.ts +9 -3
  228. package/src/system/operators.ts +290 -115
  229. package/src/system/sleep.ts +6 -2
  230. package/src/system/time.ts +18 -6
  231. package/src/system/timeout-with-predicate.ts +19 -8
  232. package/src/system/vector2.ts +101 -49
  233. package/src/system/vector3.ts +85 -36
  234. package/src/window/clipboard.ts +3 -1
  235. package/src/window/context.ts +15 -5
  236. package/src/window/cursor.ts +3 -1
  237. package/src/window/event.ts +26 -12
  238. package/src/window/mouse.ts +6 -2
  239. package/src/window/video-mode.ts +3 -1
  240. package/src/window/window.ts +119 -37
  241. package/test/native/audio-probes.cc +74 -36
  242. package/test/native/deferred-delete-probes.cc +17 -11
  243. package/test/native/drawable-probes.cc +70 -36
  244. package/test/native/exception-probes.cc +14 -9
  245. package/test/native/image-probes.cc +20 -10
  246. package/test/native/matrix-probes.cc +8 -4
  247. package/test/native/network-oracle.cc +17 -11
  248. package/test/native/render-texture-probes.cc +33 -24
  249. package/test/native/shader-probes.cc +9 -9
  250. package/test/native/shape-probes.cc +37 -23
  251. package/test/native/sprite-probes.cc +41 -25
  252. package/test/native/system-probes.cc +58 -35
  253. package/test/native/text-probes.cc +77 -44
  254. package/test/native/texture-probes.cc +43 -26
  255. package/test/native/time-probes.cc +18 -12
  256. package/test/native/transform-probes.cc +15 -10
  257. package/test/native/transformable-probes.cc +23 -17
  258. package/test/native/value-oracle.h +9 -4
  259. package/test/native/value-probes.cc +31 -23
  260. package/test/native/vertex-array-probes.cc +22 -14
  261. package/test/native/vertex-buffer-probes.cc +28 -17
  262. package/test/native/view-probes.cc +29 -17
  263. package/test/native/window-probes.cc +66 -33
  264. package/tools/ensure-sfml.cjs +9 -0
  265. package/tools/generate-network-constants.cjs +11 -6
  266. package/tools/generate-window-constants.cjs +31 -12
  267. package/docs/README.ja.md +0 -30
  268. package/docs/README.ko.md +0 -30
  269. package/docs/README.md +0 -30
  270. package/docs/README.zh-CN.md +0 -30
  271. package/docs/api.ja.md +0 -84
  272. package/docs/api.ko.md +0 -84
  273. package/docs/api.md +0 -81
  274. package/docs/api.zh-CN.md +0 -81
  275. package/docs/audio.ja.md +0 -249
  276. package/docs/audio.ko.md +0 -251
  277. package/docs/audio.md +0 -252
  278. package/docs/audio.zh-CN.md +0 -252
  279. package/docs/concepts.ja.md +0 -130
  280. package/docs/concepts.ko.md +0 -130
  281. package/docs/concepts.md +0 -131
  282. package/docs/concepts.zh-CN.md +0 -131
  283. package/docs/development.ja.md +0 -144
  284. package/docs/development.ko.md +0 -144
  285. package/docs/development.md +0 -146
  286. package/docs/development.zh-CN.md +0 -146
  287. package/docs/getting-started.ja.md +0 -154
  288. package/docs/getting-started.ko.md +0 -154
  289. package/docs/getting-started.md +0 -156
  290. package/docs/getting-started.zh-CN.md +0 -156
  291. package/docs/graphics.ja.md +0 -256
  292. package/docs/graphics.ko.md +0 -254
  293. package/docs/graphics.md +0 -255
  294. package/docs/graphics.zh-CN.md +0 -257
  295. package/docs/network.ja.md +0 -214
  296. package/docs/network.ko.md +0 -216
  297. package/docs/network.md +0 -218
  298. package/docs/network.zh-CN.md +0 -218
  299. package/docs/system.ja.md +0 -169
  300. package/docs/system.ko.md +0 -171
  301. package/docs/system.md +0 -173
  302. package/docs/system.zh-CN.md +0 -173
  303. package/docs/window.ja.md +0 -138
  304. package/docs/window.ko.md +0 -140
  305. package/docs/window.md +0 -141
  306. package/docs/window.zh-CN.md +0 -141
  307. package/native/exception-boundary.h +0 -97
  308. package/native/numeric-fields.h +0 -96
  309. package/native/shared-handle.h +0 -107
  310. package/test/tsconfig.json +0 -8
  311. package/tools/configure-lsp.cjs +0 -23
  312. package/tools/lib_downloader.cjs +0 -92
  313. package/tools/lib_downloader_urls.cjs +0 -23
package/docs/window.md DELETED
@@ -1,141 +0,0 @@
1
- # Window
2
-
3
- **English** · [简体中文](window.zh-CN.md) · [日本語](window.ja.md) · [한국어](window.ko.md)
4
-
5
- > Use RenderWindow for 2D drawing, or Window when integrating OpenGL yourself. Window operations run on the main thread.
6
-
7
- [API guide](api.md) · [Graphics](graphics.md) · [Quick start](getting-started.md)
8
-
9
- ## Creation and closing
10
-
11
- ```typescript
12
- import { RenderWindow, VideoMode, Vector2u, State, Style } from 'sfml.js';
13
-
14
- const window = new RenderWindow(
15
- new VideoMode(new Vector2u(800, 600)),
16
- 'sfml.js',
17
- {
18
- style: Style.Default,
19
- state: State.Windowed,
20
- settings: { depthBits: 24, stencilBits: 8 },
21
- },
22
- );
23
- window.close();
24
- ```
25
-
26
- Window and RenderWindow support default construction followed by `create()`. They also accept a Vector2u size or a bigint handle to an existing system window. `close()` closes the window, but the JS object can still create another window.
27
-
28
- RenderWindow satisfies both `instanceof Window` and `instanceof RenderTarget`. It supports drawing directly, querying relative mouse coordinates and serving as the source of `Texture.update(window)`.
29
-
30
- | API | Purpose |
31
- | --- | --- |
32
- | `get/setPosition()`, `get/setSize()` | Window position and client-area size |
33
- | `setMinimumSize()`, `setMaximumSize()` | Size limits; undefined removes the limit |
34
- | `setTitle()`, `setVisible()`, `setIcon()` | Title, visibility and RGBA icon |
35
- | `requestFocus()`, `hasFocus()` | Request and query focus |
36
- | `setMouseCursor()`, `setMouseCursorVisible()`, `setMouseCursorGrabbed()` | Cursor and mouse confinement |
37
- | `setKeyRepeatEnabled()`, `setJoystickThreshold()` | Input behavior |
38
- | `setVerticalSyncEnabled()`, `setFramerateLimit()` | Presentation timing |
39
- | `getSettings()`, `getNativeHandle()` | Actual context settings and system window handle |
40
-
41
- Positions use Vector2i; sizes use Vector2u. `setIcon(size, pixels)` accepts RGBA8 bytes; RenderWindow also accepts Image.
42
-
43
- ## Event loop
44
-
45
- ```typescript
46
- import { RenderWindow, Vector2u, Keyboard } from 'sfml.js';
47
-
48
- const window = new RenderWindow(new Vector2u(800, 600), 'Events');
49
- window.setFramerateLimit(60);
50
-
51
- function frame() {
52
- window.handleEvents({
53
- Closed: () => window.close(),
54
- KeyPressed: event => {
55
- if (event.code === Keyboard.Key.Escape) window.close();
56
- },
57
- Resized: event => console.log(event.size.x, event.size.y),
58
- });
59
- if (!window.isOpen()) return;
60
- window.clear();
61
- window.display();
62
- setImmediate(frame);
63
- }
64
- frame();
65
- ```
66
-
67
- `handleEvents(handlers, fallback?)` drains the event queue, preferring the handler for each event type. You can also pass a single function to handle all events.
68
-
69
- Use `pollEvent()` for manual dispatch:
70
-
71
- ```typescript
72
- let event;
73
- while ((event = window.pollEvent())) {
74
- if (event.is('Closed')) window.close();
75
- const key = event.getIf('KeyPressed');
76
- if (key) console.log(key.code, key.scancode);
77
- }
78
- ```
79
-
80
- `pollEvent()` returns undefined when no event is available. Event data is a union discriminated by kind; use `is()`, `getIf()` and `visit()` to narrow or access it. TextEntered uses Unicode code points.
81
-
82
- `waitEvent(timeout = Time.Zero)` blocks synchronously and returns undefined on timeout or closing. Frame loops that also need to process Node I/O should use pollEvent/handleEvents and yield to the event loop between frames.
83
-
84
- ## Real-time input and system features
85
-
86
- | API | Description |
87
- | --- | --- |
88
- | `Keyboard.isKeyPressed(key)` | Current key-code state |
89
- | `Keyboard.isKeyPressed(scancode, 'scancode')` | Current physical scancode state |
90
- | `Keyboard.localize()`/`delocalize()`/`getDescription()` | Current keyboard layout mapping and descriptions |
91
- | `Mouse.getPosition(window?)`/`setPosition(position, window?)` | Uses screen coordinates when the window is omitted |
92
- | `Mouse.isButtonPressed(button)` | Current mouse-button state |
93
- | Joystick | Connection, buttons, axes and device identification; call `update()` without a window loop |
94
- | Sensor | Check `isAvailable()` before enabling and reading |
95
- | Clipboard | `getString()`/`setString()`, supporting JS Unicode strings |
96
- | Touch | Touch-point state and position; SFML 3.1.0 deprecates the real-time Touch API |
97
-
98
- Enums in input namespaces share the same objects as their top-level counterparts, such as `Keyboard.Key` and `KeyboardKey`.
99
-
100
- `Cursor.createFromSystem()` and `createFromPixels()` return undefined on failure; constructor failures throw. A window keeps its active Cursor alive. On macOS, create a window before using system cursors.
101
-
102
- VideoMode uses `size` and `bitsPerPixel`; `getDesktopMode()` and `getFullscreenModes()` query device modes, and `isValid()` validates fullscreen modes. Do not assume a machine provides any particular number of fullscreen modes.
103
-
104
- ## OpenGL and Vulkan
105
-
106
- Context can create an independent OpenGL context, with activation, actual settings, extension queries and function-address queries. `Context.getActiveContextId()` returns a bigint, or `0n` when no context is active. `getFunction()` returns an address as bigint; calling it requires native code with a matching signature.
107
-
108
- RenderWindow's `setActive()`, `pushGLStates()`, `popGLStates()` and `resetGLStates()` support mixing SFML with custom OpenGL. Submit SFML commands before modifying GL state directly, and pair push/pop in the same context.
109
-
110
- The Vulkan namespace provides:
111
-
112
- - `isAvailable(requireGraphics = true)`.
113
- - `getFunction(name)`.
114
- - `getGraphicsRequiredInstanceExtensions()`.
115
-
116
- `window.createVulkanSurface(instance, allocator = 0n)` returns a bigint surface handle, or undefined on failure. The caller is responsible for the instance, allocator and surface destruction.
117
-
118
- SFML 3.1.0's macOS build does not provide a Vulkan backend, so these queries report unavailability. Installing MoltenVK does not change SFML's platform branch. Successful Windows/X11 paths require validation in those environments.
119
-
120
- ## Run the demo
121
-
122
- After building, run `node examples/window.cjs --frames=120` to inspect events, key codes, pointer positions and window properties; omit the frame count to run continuously.
123
-
124
- | Key | Action |
125
- | --- | --- |
126
- | F1/F2 | Cursor type/visibility |
127
- | F3/F4 | Key repeat/vertical sync |
128
- | F5/F6 | Window size/size limits |
129
- | F7/F8 | Change title/hide for 1 second, then restore |
130
- | F9/F10 | Event API/move window |
131
- | Esc | Close |
132
-
133
- On macOS, you may also need to hold Fn. Determine joystick, sensor, touch and Vulkan capabilities from device queries; a passing CI build does not mean all of these hardware paths have been verified.
134
-
135
- <a id="sfml-cpp-reference"></a>
136
-
137
- ## SFML C++ reference
138
-
139
- See the original [Window](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Window.html), [RenderWindow](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1RenderWindow.html), [Event](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Event.html), [VideoMode](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1VideoMode.html) and [Cursor](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Cursor.html) references for upstream window, event and cursor concepts.
140
-
141
- C++ event types and coordinate rules apply as documented here. JavaScript dispatch uses string event names and typed payloads, and frame loops yield through `setImmediate()`; `waitEvent()` remains synchronous.
@@ -1,141 +0,0 @@
1
- # Window
2
-
3
- [English](window.md) · **简体中文** · [日本語](window.ja.md) · [한국어](window.ko.md)
4
-
5
- > 二维绘制使用 RenderWindow;自行接入 OpenGL 时可使用 Window。窗口操作在主线程执行。
6
-
7
- [API 导航](api.zh-CN.md) · [Graphics](graphics.zh-CN.md) · [快速开始](getting-started.zh-CN.md)
8
-
9
- ## 创建与关闭
10
-
11
- ```typescript
12
- import { RenderWindow, VideoMode, Vector2u, State, Style } from 'sfml.js';
13
-
14
- const window = new RenderWindow(
15
- new VideoMode(new Vector2u(800, 600)),
16
- 'sfml.js',
17
- {
18
- style: Style.Default,
19
- state: State.Windowed,
20
- settings: { depthBits: 24, stencilBits: 8 },
21
- },
22
- );
23
- window.close();
24
- ```
25
-
26
- Window 与 RenderWindow 支持空构造后调用 `create()`,也接受 Vector2u 尺寸或已有系统窗口的 bigint 句柄。`close()` 关闭窗口,JS 对象仍可再次 create。
27
-
28
- RenderWindow 同时满足 `instanceof Window` 与 `instanceof RenderTarget`,可以直接绘制、查询鼠标相对坐标,也能作为 `Texture.update(window)` 的来源。
29
-
30
- | 接口 | 用途 |
31
- | --- | --- |
32
- | `get/setPosition()`、`get/setSize()` | 窗口位置与客户区尺寸 |
33
- | `setMinimumSize()`、`setMaximumSize()` | 尺寸限制;undefined 解除限制 |
34
- | `setTitle()`、`setVisible()`、`setIcon()` | 标题、显隐、RGBA 图标 |
35
- | `requestFocus()`、`hasFocus()` | 焦点请求与查询 |
36
- | `setMouseCursor()`、`setMouseCursorVisible()`、`setMouseCursorGrabbed()` | 光标及鼠标限制 |
37
- | `setKeyRepeatEnabled()`、`setJoystickThreshold()` | 输入行为 |
38
- | `setVerticalSyncEnabled()`、`setFramerateLimit()` | 呈现节奏 |
39
- | `getSettings()`、`getNativeHandle()` | 实际上下文设置与系统窗口句柄 |
40
-
41
- 位置使用 Vector2i,尺寸使用 Vector2u。`setIcon(size, pixels)` 接受 RGBA8 字节;RenderWindow 还接受 Image。
42
-
43
- ## 事件循环
44
-
45
- ```typescript
46
- import { RenderWindow, Vector2u, Keyboard } from 'sfml.js';
47
-
48
- const window = new RenderWindow(new Vector2u(800, 600), 'Events');
49
- window.setFramerateLimit(60);
50
-
51
- function frame() {
52
- window.handleEvents({
53
- Closed: () => window.close(),
54
- KeyPressed: event => {
55
- if (event.code === Keyboard.Key.Escape) window.close();
56
- },
57
- Resized: event => console.log(event.size.x, event.size.y),
58
- });
59
- if (!window.isOpen()) return;
60
- window.clear();
61
- window.display();
62
- setImmediate(frame);
63
- }
64
- frame();
65
- ```
66
-
67
- `handleEvents(handlers, fallback?)` 排空事件队列,优先调用对应类型的处理器;也可传入单个函数处理全部事件。
68
-
69
- 需要手动分派时使用 `pollEvent()`:
70
-
71
- ```typescript
72
- let event;
73
- while ((event = window.pollEvent())) {
74
- if (event.is('Closed')) window.close();
75
- const key = event.getIf('KeyPressed');
76
- if (key) console.log(key.code, key.scancode);
77
- }
78
- ```
79
-
80
- `pollEvent()` 在没有事件时返回 undefined。Event 的 data 是以 kind 区分的联合类型,`is()`、`getIf()` 和 `visit()` 可用于收窄或访问数据。TextEntered 使用 Unicode 码点。
81
-
82
- `waitEvent(timeout = Time.Zero)` 是同步阻塞接口,超时或关闭时返回 undefined。需要同时处理 Node I/O 的帧循环使用 pollEvent/handleEvents,并在帧间让出事件循环。
83
-
84
- ## 实时输入与系统功能
85
-
86
- | 接口 | 说明 |
87
- | --- | --- |
88
- | `Keyboard.isKeyPressed(key)` | 当前键码状态 |
89
- | `Keyboard.isKeyPressed(scancode, 'scancode')` | 当前物理扫描码状态 |
90
- | `Keyboard.localize()`/`delocalize()`/`getDescription()` | 当前键盘布局映射及描述 |
91
- | `Mouse.getPosition(window?)`/`setPosition(position, window?)` | 省略窗口时使用屏幕坐标 |
92
- | `Mouse.isButtonPressed(button)` | 当前鼠标按钮状态 |
93
- | Joystick | 连接、按钮、轴及设备标识;无窗口循环时调用 `update()` |
94
- | Sensor | 先 `isAvailable()`,再启用及读取 |
95
- | Clipboard | `getString()`/`setString()`,支持 JS Unicode 字符串 |
96
- | Touch | 触点状态与位置;SFML 3.1.0 已弃用实时 Touch API |
97
-
98
- 输入命名空间中的枚举与顶层枚举共用同一对象,如 `Keyboard.Key` 与 `KeyboardKey`。
99
-
100
- `Cursor.createFromSystem()`、`createFromPixels()` 失败时返回 undefined,构造函数失败则抛错。窗口会保活正在使用的 Cursor。macOS 使用系统光标前需先创建窗口。
101
-
102
- VideoMode 使用 `size` 与 `bitsPerPixel`;`getDesktopMode()`、`getFullscreenModes()` 查询设备模式,`isValid()` 判断全屏模式。不要假设机器一定提供特定数量的全屏模式。
103
-
104
- ## OpenGL 与 Vulkan
105
-
106
- Context 可创建独立 OpenGL 上下文,提供激活、实际设置、扩展查询及函数地址查询。`Context.getActiveContextId()` 返回 bigint,未激活时为 `0n`。地址由 `getFunction()` 以 bigint 返回,调用它需要匹配签名的原生代码。
107
-
108
- RenderWindow 的 `setActive()`、`pushGLStates()`、`popGLStates()` 与 `resetGLStates()` 用于混合 SFML 和自定义 OpenGL。直接修改 GL 状态前先提交 SFML 命令,push/pop 必须在同一上下文配对。
109
-
110
- Vulkan 命名空间提供:
111
-
112
- - `isAvailable(requireGraphics = true)`。
113
- - `getFunction(name)`。
114
- - `getGraphicsRequiredInstanceExtensions()`。
115
-
116
- `window.createVulkanSurface(instance, allocator = 0n)` 返回 bigint 表面句柄,失败为 undefined。实例、分配器与表面销毁由调用方负责。
117
-
118
- SFML 3.1.0 的 macOS 构建不提供 Vulkan 后端;这些查询会反映不可用,安装 MoltenVK 不改变 SFML 的该平台分支。Windows/X11 的成功路径需要在对应环境验证。
119
-
120
- ## 运行演示
121
-
122
- 构建后运行 `node examples/window.cjs --frames=120`,查看事件、键码、指针位置和窗口属性;省略帧数则持续运行。
123
-
124
- | 按键 | 行为 |
125
- | --- | --- |
126
- | F1/F2 | 光标类型/显隐 |
127
- | F3/F4 | 按键重复/垂直同步 |
128
- | F5/F6 | 窗口尺寸/尺寸限制 |
129
- | F7/F8 | 修改标题/隐藏 1 秒后恢复 |
130
- | F9/F10 | 事件 API/移动窗口 |
131
- | Esc | 关闭 |
132
-
133
- macOS 可能需要同时按 Fn。摇杆、传感器、触摸和 Vulkan 能力按设备查询结果判断;CI 构建通过不等于这些硬件路径都已验证。
134
-
135
- <a id="sfml-cpp-reference"></a>
136
-
137
- ## SFML C++ 参考
138
-
139
- 窗口与事件参考 [sf::Window](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Window.html)、[sf::RenderWindow](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1RenderWindow.html)、[sf::Event](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Event.html);显示模式与光标参考 [sf::VideoMode](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1VideoMode.html) 和 [sf::Cursor](https://www.sfml-dev.org/documentation/3.1.0/classsf_1_1Cursor.html)。
140
-
141
- 上游事件类型和坐标规则可作为概念参考。JS 用字符串事件名和类型化载荷分派事件,并通过 `setImmediate()` 在帧间让出事件循环;`waitEvent()` 仍是同步等待,不能将 C++ 主循环直接搬入 Node.js。
@@ -1,97 +0,0 @@
1
- #pragma once
2
-
3
- #include <nan.h>
4
- #include <SFML/System/Exception.hpp>
5
-
6
- #include <exception>
7
-
8
- namespace sfmljs {
9
-
10
- inline v8::Local<v8::String> ErrorStateKey() {
11
- return Nan::New("sfml.error.state").ToLocalChecked();
12
- }
13
-
14
- inline void InitializeErrors(v8::Local<v8::Object> target) {
15
- auto state = Nan::New<v8::Object>();
16
- Nan::Set(state, Nan::New("prototype").ToLocalChecked(), Nan::Undefined()).FromJust();
17
- Nan::Set(target, Nan::New("errorState").ToLocalChecked(), state).FromJust();
18
- Nan::SetPrivate(Nan::GetCurrentContext()->Global(), ErrorStateKey(), state)
19
- .FromJust();
20
- }
21
-
22
- // The JS realm owns its prototype. No persistent C++ handle or teardown hook.
23
- inline v8::Local<v8::Value> Error(const char* message) {
24
- auto error = Nan::Error(message);
25
- auto object = error.As<v8::Object>();
26
- v8::Local<v8::Value> state;
27
- v8::Local<v8::Value> prototype;
28
- if (Nan::GetPrivate(Nan::GetCurrentContext()->Global(), ErrorStateKey())
29
- .ToLocal(&state) && state->IsObject() &&
30
- Nan::Get(state.As<v8::Object>(), Nan::New("prototype").ToLocalChecked())
31
- .ToLocal(&prototype) && prototype->IsObject()) {
32
- object->SetPrototype(Nan::GetCurrentContext(), prototype).FromJust();
33
- }
34
- Nan::Set(object, Nan::New("name").ToLocalChecked(),
35
- Nan::New("SFMLError").ToLocalChecked()).FromJust();
36
- return error;
37
- }
38
-
39
- inline void ThrowError(const char* message) {
40
- Nan::ThrowError(Error(message));
41
- }
42
-
43
- template <typename Action, typename Failure>
44
- void GuardExceptions(Action&& action, Failure&& failure) {
45
- try {
46
- action();
47
- } catch (const sf::Exception& error) {
48
- // Match the prebuilt library's concrete type across DSO boundaries.
49
- failure(error.what());
50
- } catch (const std::exception& error) {
51
- failure(error.what());
52
- } catch (...) {
53
- failure("Unknown native exception");
54
- }
55
- }
56
-
57
- template <Nan::FunctionCallback Callback>
58
- void ExceptionBoundary(const Nan::FunctionCallbackInfo<v8::Value>& info) {
59
- GuardExceptions([&] { Callback(info); },
60
- [](const char* message) { ThrowError(message); });
61
- }
62
-
63
- // The callback is a compile-time parameter: no per-call dispatch allocation.
64
- template <Nan::FunctionCallback Callback>
65
- void SetMethod(v8::Local<v8::Object> target, const char* name) {
66
- Nan::SetMethod(target, name, ExceptionBoundary<Callback>);
67
- }
68
-
69
- // libuv executes these callbacks outside the synchronous NAN call stack.
70
- class AsyncWorker : public Nan::AsyncWorker {
71
- public:
72
- using Nan::AsyncWorker::AsyncWorker;
73
-
74
- void Execute() final {
75
- GuardExceptions([this] { ExecuteWork(); },
76
- [this](const char* message) { SetErrorMessage(message); });
77
- }
78
-
79
- void HandleOKCallback() final {
80
- GuardExceptions([this] { CompleteWork(); }, [this](const char* message) {
81
- SetErrorMessage(message);
82
- HandleErrorCallback();
83
- });
84
- }
85
-
86
- void HandleErrorCallback() final {
87
- Nan::HandleScope scope;
88
- v8::Local<v8::Value> args[] = {Error(ErrorMessage())};
89
- callback->Call(1, args, async_resource);
90
- }
91
-
92
- protected:
93
- virtual void ExecuteWork() = 0;
94
- virtual void CompleteWork() = 0;
95
- };
96
-
97
- } // namespace sfmljs
@@ -1,96 +0,0 @@
1
- #pragma once
2
-
3
- #include "shared-handle.h"
4
-
5
- #include <algorithm>
6
- #include <cstdint>
7
- #include <type_traits>
8
- #include <vector>
9
-
10
- namespace sfmljs {
11
-
12
- // Explicit instantiation can name private members (C++ [temp.explicit]).
13
- // Use member pointers from the installed headers, never replica class layouts.
14
- template <typename Tag, typename Tag::Type Pointer>
15
- struct MemberAccess {
16
- friend typename Tag::Type Member(Tag) { return Pointer; }
17
- };
18
-
19
- #define SFMLJS_MEMBER(Tag, Class, Value, Name) \
20
- struct Tag { \
21
- using Type = Value Class::*; \
22
- friend Type Member(Tag); \
23
- }; \
24
- template struct sfmljs::MemberAccess<Tag, &Class::Name>
25
-
26
- template <typename Tag, typename Object>
27
- decltype(auto) Field(Object& object) {
28
- return object.*Member(Tag{});
29
- }
30
-
31
- // Map numeric regions once. Adjacent fields share a backing store; strings,
32
- // pointers and containers between regions are never exposed to JavaScript.
33
- class NumericFields {
34
- public:
35
- template <typename T>
36
- NumericFields& Add(const char* name, const T& value, const char* type = nullptr) {
37
- if (!type) {
38
- if constexpr (std::is_same_v<T, bool>) type = "bool";
39
- else if constexpr (std::is_same_v<T, float>) type = "f32";
40
- else if constexpr (std::is_same_v<T, double>) type = "f64";
41
- else if constexpr (sizeof(T) == 8) type = "u64";
42
- else {
43
- static_assert(sizeof(T) == 4);
44
- type = "u32";
45
- }
46
- }
47
- fields_.push_back({name, type, reinterpret_cast<std::uintptr_t>(&value),
48
- sizeof(T)});
49
- return *this;
50
- }
51
-
52
- template <typename T>
53
- v8::Local<v8::Object> Map(const std::shared_ptr<T>& owner) {
54
- std::sort(fields_.begin(), fields_.end(),
55
- [](const auto& a, const auto& b) { return a.address < b.address; });
56
- auto buffers = Nan::New<v8::Array>();
57
- auto fields = Nan::New<v8::Object>();
58
- std::uint32_t region = 0;
59
- for (std::size_t begin = 0; begin < fields_.size(); ++region) {
60
- const auto start = fields_[begin].address;
61
- auto end = start + fields_[begin].size;
62
- auto next = begin + 1;
63
- // Exact adjacency only: no hidden members or padding are mapped.
64
- while (next < fields_.size() && fields_[next].address == end) {
65
- end += fields_[next++].size;
66
- }
67
- Nan::Set(buffers, region, MapShared(v8::Isolate::GetCurrent(), owner,
68
- reinterpret_cast<void*>(start), end - start)).FromJust();
69
- for (; begin < next; ++begin) {
70
- const auto& field = fields_[begin];
71
- auto descriptor = Nan::New<v8::Array>(3);
72
- Nan::Set(descriptor, 0, Nan::New(field.type).ToLocalChecked()).FromJust();
73
- Nan::Set(descriptor, 1, Nan::New(region)).FromJust();
74
- Nan::Set(descriptor, 2, Nan::New(
75
- static_cast<std::uint32_t>(field.address - start))).FromJust();
76
- Nan::Set(fields, Nan::New(field.name).ToLocalChecked(), descriptor)
77
- .FromJust();
78
- }
79
- }
80
- auto result = Nan::New<v8::Object>();
81
- Nan::Set(result, Nan::New("buffers").ToLocalChecked(), buffers).FromJust();
82
- Nan::Set(result, Nan::New("fields").ToLocalChecked(), fields).FromJust();
83
- return result;
84
- }
85
-
86
- private:
87
- struct Entry {
88
- const char* name;
89
- const char* type;
90
- std::uintptr_t address;
91
- std::size_t size;
92
- };
93
- std::vector<Entry> fields_;
94
- };
95
-
96
- } // namespace sfmljs
@@ -1,107 +0,0 @@
1
- #pragma once
2
-
3
- #include <nan.h>
4
-
5
- #include <memory>
6
- #include <unordered_map>
7
- #include <utility>
8
-
9
- namespace sfmljs {
10
-
11
- // V8 retains instantiated template metadata in its native context. Reuse one
12
- // shape per Node environment, and release its persistent before isolate teardown.
13
- // All handle types have the same layout; the private marker below checks T.
14
- class SharedHandleTemplate final {
15
- public:
16
- static v8::Local<v8::ObjectTemplate> Get() {
17
- auto* environment = node::GetCurrentEnvironment(Nan::GetCurrentContext());
18
- auto found = templates_.find(environment);
19
- if (found == templates_.end()) {
20
- auto* cache = new SharedHandleTemplate(environment);
21
- found = templates_.emplace(environment, cache).first;
22
- node::AddEnvironmentCleanupHook(v8::Isolate::GetCurrent(), Cleanup, cache);
23
- }
24
- return Nan::New(found->second->shape_);
25
- }
26
-
27
- private:
28
- explicit SharedHandleTemplate(node::Environment* environment)
29
- : environment_(environment) {
30
- auto shape = Nan::New<v8::ObjectTemplate>();
31
- shape->SetInternalFieldCount(1);
32
- shape_.Reset(shape);
33
- }
34
-
35
- static void Cleanup(void* data) {
36
- auto* cache = static_cast<SharedHandleTemplate*>(data);
37
- cache->shape_.Reset();
38
- templates_.erase(cache->environment_);
39
- delete cache;
40
- }
41
-
42
- // Worker threads must never share V8 handles. The cleanup hook also removes
43
- // entries when an environment is replaced on the same thread.
44
- inline static thread_local
45
- std::unordered_map<node::Environment*, SharedHandleTemplate*> templates_;
46
- node::Environment* environment_;
47
- Nan::Persistent<v8::ObjectTemplate> shape_;
48
- };
49
-
50
- template <typename T>
51
- class SharedHandle final : public Nan::ObjectWrap {
52
- public:
53
- static v8::Local<v8::Object> Create(std::shared_ptr<T> owner) {
54
- auto object = Nan::NewInstance(SharedHandleTemplate::Get()).ToLocalChecked();
55
- auto* handle = new SharedHandle(std::move(owner));
56
- handle->Wrap(object);
57
- Nan::SetPrivate(object, Key(),
58
- Nan::New<v8::External>(&identity_)).FromJust();
59
- return object;
60
- }
61
-
62
- static SharedHandle* TryFrom(v8::Local<v8::Value> value) {
63
- if (value->IsObject()) {
64
- auto object = value.As<v8::Object>();
65
- v8::Local<v8::Value> marker;
66
- if (object->InternalFieldCount() == 1 &&
67
- Nan::GetPrivate(object, Key()).ToLocal(&marker) &&
68
- marker->IsExternal() &&
69
- marker.As<v8::External>()->Value() == &identity_) {
70
- return Nan::ObjectWrap::Unwrap<SharedHandle>(object);
71
- }
72
- }
73
- return nullptr;
74
- }
75
-
76
- static SharedHandle* From(v8::Local<v8::Value> value) {
77
- auto* handle = TryFrom(value);
78
- if (!handle) Nan::ThrowTypeError("Expected a matching native handle");
79
- return handle;
80
- }
81
-
82
- const std::shared_ptr<T>& owner() const { return owner_; }
83
-
84
- private:
85
- explicit SharedHandle(std::shared_ptr<T> owner) : owner_(std::move(owner)) {}
86
-
87
- static v8::Local<v8::String> Key() {
88
- return Nan::New("sfml.shared.owner").ToLocalChecked();
89
- }
90
-
91
- inline static char identity_;
92
- std::shared_ptr<T> owner_;
93
- };
94
-
95
- template <typename T>
96
- v8::Local<v8::ArrayBuffer> MapShared(v8::Isolate* isolate,
97
- const std::shared_ptr<T>& owner,
98
- void* data, std::size_t size) {
99
- auto* viewOwner = new std::shared_ptr<T>(owner);
100
- auto backing = v8::ArrayBuffer::NewBackingStore(data, size,
101
- [](void*, size_t, void* retained) {
102
- delete static_cast<std::shared_ptr<T>*>(retained);
103
- }, viewOwner);
104
- return v8::ArrayBuffer::New(isolate, std::move(backing));
105
- }
106
-
107
- } // namespace sfmljs
@@ -1,8 +0,0 @@
1
- {
2
- "extends": "../tsconfig.json",
3
- "compilerOptions": {
4
- "noEmit": true,
5
- "rootDir": ".."
6
- },
7
- "include": ["*.types.ts"]
8
- }
@@ -1,23 +0,0 @@
1
- 'use strict';
2
-
3
- const { spawnSync } = require('node:child_process');
4
- const { readFileSync, writeFileSync } = require('node:fs');
5
- const path = require('node:path');
6
-
7
- const root = path.resolve(__dirname, '..');
8
- const result = spawnSync(process.execPath, [
9
- require.resolve('node-gyp/bin/node-gyp.js'),
10
- 'configure', '--', '-f', 'compile_commands_json',
11
- ], { cwd: root, stdio: 'inherit' });
12
- if (result.error) throw result.error;
13
- if (result.status !== 0) process.exit(result.status ?? 1);
14
-
15
- const generated = path.join(root, 'build/Release/compile_commands.json');
16
- const commands = JSON.parse(readFileSync(generated, 'utf8'));
17
- for (const command of commands) {
18
- // GYP emits "."; clangd requires an absolute working directory.
19
- command.directory = root;
20
- }
21
- const database = path.join(root, 'build/compile_commands.json');
22
- writeFileSync(database, JSON.stringify(commands, null, 2) + '\n');
23
- console.log(`[sfml.js] Generated ${database}`);