@kmamal/sdl 1.0.0-3 → 1.0.0-5

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/CHANGELOG.md CHANGED
@@ -18,6 +18,7 @@ The library now builds against SDL3 (3.4.x) instead of SDL2. This release contai
18
18
  - Audio and video formats are reported using the platform-independent enums. The platform-dependent ones are only used as input.
19
19
  - Character keys are reported as the unshifted character (`'ü'` instead of `'Ü'`), so `getKey(getScancode('ü'))` round-trips.
20
20
  - steamHandle is now reported as a BigInt.
21
+ - `@kmamal/sdl/helpers` is now `@kmamal/sdl/helpers`, and includes a lot of extra stuff.
21
22
 
22
23
  ### Added
23
24
 
@@ -31,7 +32,6 @@ The library now builds against SDL3 (3.4.x) instead of SDL2. This release contai
31
32
  - Audio device objects report the `format`, `channels`, `frequency`, and `buffered` the device is running with while streams are open on them.
32
33
  - Gamepad buttons `misc1` and `touchpad` are now reported instead of arriving with `button: null`.
33
34
  - Pixel-format helpers similar to audio format helpers.
34
- - More stuff in `@kmamal/sdl/helpers`
35
35
  - More scancodes and keys
36
36
 
37
37
  ### Fixed
package/README.md CHANGED
@@ -9,7 +9,7 @@
9
9
  > Most of the API is unchanged, but several changes break compatibility.
10
10
  > The [migration guide](https://github.com/kmamal/node-sdl/tree/master/docs/migrating-to-sdl3.md) lists them all.
11
11
 
12
- SDL bindings for Node.js. Gives applications access to systems that Node.js does not normally provide:
12
+ SDL bindings for Node.js. Gives desktop applications access to features that Node.js does not normally provide:
13
13
 
14
14
  - 💻 Window management
15
15
  - ⌨ Keyboard
@@ -22,13 +22,15 @@ SDL bindings for Node.js. Gives applications access to systems that Node.js does
22
22
  - 🔋 Battery status
23
23
  - 🧭 Sensors
24
24
 
25
- The bindings also let you use Canvas2D, WebGL, and WebGPU without a browser, through these libraries:
25
+ In addition, all these things can now be used without a browser:
26
26
 
27
27
  - __Canvas2D:__ [@napi-rs/canvas](https://www.npmjs.com/package/@napi-rs/canvas). In my experience, it is the fastest of the many canvas libraries on npm.
28
- - __WebGL:__ [@kmamal/gl](https://github.com/kmamal/headless-gl#readme). I forked [headless-gl](https://github.com/stackgl/headless-gl#readme) and modified it to render directly to SDL windows.
29
- - __WebGPU:__ [@kmamal/gpu](https://github.com/kmamal/gpu#readme). I forked [Google Dawn](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/dawn/node/) and modified it to render directly to SDL windows.
28
+ - __WebGL:__ [@kmamal/gl](https://github.com/kmamal/headless-gl#readme). A fork of [headless-gl](https://github.com/stackgl/headless-gl#readme) modified to render directly to SDL windows.
29
+ - __WebGPU:__ [@kmamal/gpu](https://github.com/kmamal/gpu#readme). A fork of [Google Dawn](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/dawn/node/) modified to render directly to SDL windows.
30
+ - __Web Audio:__ [@kmamal/audio](https://github.com/kmamal/audio#readme). An implementation of the Web Audio API that uses `@kmamal/sdl` for audio playback and recording.
31
+ - __Three.js:__ [@kmamal/three](https://github.com/kmamal/three#readme). A fork of [Three.js](https://threejs.org/) ported to the desktop via tha above libraries.
30
32
 
31
- The package officially supports Linux (X11 and Wayland), Mac, and Windows.
33
+ This package officially supports Linux (X11 and Wayland), Mac, and Windows.
32
34
  It should work on any system that both SDL and Node.js support, but I haven't tried others.
33
35
  Prebuilt binaries exist for x64 and arm architectures on all supported platforms.
34
36
 
@@ -90,8 +92,8 @@ import createContext from '@kmamal/gl'
90
92
 
91
93
  // Setup
92
94
  const window = sdl.video.createWindow({ title: "WebGL", opengl: true })
93
- const { pixelWidth: width, pixelHeight: height, native } = window
94
- const gl = createContext(width, height, { window: native })
95
+ const { pixelWidth: width, pixelHeight: height } = window
96
+ const gl = createContext(width, height, { window })
95
97
 
96
98
  // Clear screen to red
97
99
  gl.clearColor(1, 0, 0, 1)
@@ -134,6 +136,18 @@ renderer.swap()
134
136
 
135
137
  ```
136
138
 
139
+ ### Web Audio
140
+
141
+ ```js
142
+ // TODO
143
+ ```
144
+
145
+ ### Three.js
146
+
147
+ ```js
148
+ // TODO
149
+ ```
150
+
137
151
  # Documentation
138
152
 
139
153
  The full [API Reference](https://github.com/kmamal/node-sdl/tree/master/docs/api-reference.md) documents every function.
package/binding.gyp CHANGED
@@ -27,6 +27,7 @@
27
27
  # Node-API version of the oldest supported Node.js (v22.0.0)
28
28
  'NAPI_VERSION=9',
29
29
  'NODE_ADDON_API_DISABLE_DEPRECATED',
30
+ 'NODE_API_SWALLOW_UNTHROWABLE_EXCEPTIONS',
30
31
  ],
31
32
  'cflags': ['-Werror', '-Wall', '-Wextra'],
32
33
  'conditions': [
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.0.0-3",
2
+ "version": "1.0.0-5",
3
3
  "name": "@kmamal/sdl",
4
4
  "description": "SDL bindings for Node.js",
5
5
  "keywords": [
@@ -50,9 +50,9 @@
50
50
  "types": "./src/types/index.d.ts",
51
51
  "default": "./src/javascript/index.js"
52
52
  },
53
- "./helpers": {
54
- "types": "./src/types/helpers.d.ts",
55
- "default": "./src/javascript/helpers.js"
53
+ "./worker": {
54
+ "types": "./src/types/worker.d.ts",
55
+ "default": "./src/javascript/worker.js"
56
56
  }
57
57
  },
58
58
  "gypfile": true,
@@ -69,7 +69,7 @@
69
69
  "devDependencies": {
70
70
  "@kmamal/evdev": "0.0.8",
71
71
  "@kmamal/testing": "0.0.34",
72
- "@types/node": "26.6.4",
72
+ "@types/node": "26.6.5",
73
73
  "node-addon-api": "8.9.2",
74
74
  "node-gyp": "13.1.0"
75
75
  },
@@ -84,6 +84,6 @@
84
84
  "@kmamal/evdev": true
85
85
  },
86
86
  "dependencies": {
87
- "modern-tar": "0.8.5"
87
+ "modern-tar": "0.8.6"
88
88
  }
89
89
  }
package/scripts/build.mjs CHANGED
@@ -28,13 +28,8 @@ if (process.env.CROSS_COMPILE_ARCH) {
28
28
  archFlag = `--arch ${process.env.CROSS_COMPILE_ARCH}`
29
29
  }
30
30
 
31
- let parallelFlag = '-j max'
32
- if (C.noParallel) {
33
- parallelFlag = ''
34
- }
35
-
36
31
  process.chdir(C.dir.root)
37
- execSync(`npx -y node-gyp rebuild ${archFlag} ${parallelFlag} --verbose`, {
32
+ execSync(`npx -y node-gyp rebuild ${archFlag} -j max --verbose`, {
38
33
  stdio: 'inherit',
39
34
  env: {
40
35
  ...process.env,
@@ -17,7 +17,6 @@ const [ , owner, repo ] = pkg.repository.url.match(/([^/:]+)\/([^/]+)\.git$/u)
17
17
  const isSet = (value) => ![ undefined, '', '0', 'false' ].includes(value)
18
18
  const fromSource = isSet(process.env.NODE_SDL_FROM_SOURCE)
19
19
  const systemSdl = isSet(process.env.NODE_SDL_SYSTEM)
20
- const noParallel = isSet(process.env.NO_PARALLEL)
21
20
 
22
21
  const { platform, arch } = process
23
22
  const targetArch = process.env.CROSS_COMPILE_ARCH || arch
@@ -30,7 +29,6 @@ module.exports = {
30
29
  dir,
31
30
  fromSource,
32
31
  systemSdl,
33
- noParallel,
34
32
  version,
35
33
  isPrerelease,
36
34
  owner,
@@ -491,6 +491,7 @@ const poll = () => {
491
491
 
492
492
  const withoutPolling = (fn) => {
493
493
  const prevValue = polling
494
+ polling = true
494
495
  try { fn() }
495
496
  finally { polling = prevValue }
496
497
  }
@@ -1,5 +1,5 @@
1
1
  const { isMainThread } = require('node:worker_threads')
2
- if (!isMainThread) { throw new Error('@kmamal/sdl can only be used in the main thread') }
2
+ if (!isMainThread) { throw new Error("@kmamal/sdl can only be used in the main thread, import @kmamal/sdl/worker in workers") }
3
3
 
4
4
  const Bindings = require('./bindings')
5
5
  const Globals = require('./globals')
@@ -1,6 +1,39 @@
1
+ const { isMainThread } = require('node:worker_threads')
2
+ if (isMainThread) { throw new Error("@kmamal/sdl/worker can only be used in worker threads, import @kmamal/sdl in the main thread") }
3
+
4
+ const Globals = require('./globals')
5
+
6
+ Globals.events = {
7
+ poll () {},
8
+ withoutPolling (fn) { fn() },
9
+ switchToPollingFast () {},
10
+ switchToPollingSlow () {},
11
+ }
12
+
1
13
  const Enums = require('./enums')
2
14
  const { getFormatHelpers: getAudioFormatHelpers } = require('./audio/format-helpers')
3
15
  const { getFormatHelpers: getVideoFormatHelpers } = require('./video/format-helpers')
16
+ const { AudioPlaybackStream } = require('./audio/audio-playback-stream')
17
+ const { AudioRecordingStream } = require('./audio/audio-recording-stream')
18
+ const { makeDefault: makeDefaultDevice } = require('./audio/device')
19
+
20
+ const makeModule = (type, Stream) => {
21
+ const defaultDevice = makeDefaultDevice()
22
+
23
+ return {
24
+ openDevice (device = null, options = {}) {
25
+ if (device === null) { device = defaultDevice }
26
+ else {
27
+ if (typeof device !== 'object') { throw Object.assign(new Error("device must be an object"), { device }) }
28
+ const { id } = device
29
+ if (id !== null && !Number.isInteger(id)) { throw Object.assign(new Error("device.id must be an integer or null"), { id }) }
30
+ if (id !== null && (id < 0 || id > 2 ** 32 - 1)) { throw Object.assign(new Error("device.id must be an unsigned 32-bit integer"), { id }) }
31
+ }
32
+
33
+ return new Stream(device, options)
34
+ },
35
+ }
36
+ }
4
37
 
5
38
  module.exports = {
6
39
  video: {
@@ -48,5 +81,8 @@ module.exports = {
48
81
  if (!(buffer instanceof Buffer)) { throw Object.assign(new Error("buffer must be a Buffer"), { buffer }) }
49
82
  return getAudioFormatHelpers(format).writer.call(buffer, value, offset)
50
83
  },
84
+
85
+ playback: makeModule('playback', AudioPlaybackStream),
86
+ recording: makeModule('recording', AudioRecordingStream),
51
87
  },
52
88
  }
@@ -1,12 +1,19 @@
1
1
  #include "audio.h"
2
+ #include "global.h"
2
3
  #include <SDL3/SDL.h>
3
4
  #include <string>
4
5
  #include <sstream>
6
+ #include <mutex>
5
7
 
6
8
  std::map<bool, std::string> audio::device_types;
7
9
  std::map<SDL_AudioFormat, std::string> audio::formats;
8
10
 
9
- static std::map<SDL_AudioDeviceID, SDL_AudioStream *> open_streams;
11
+ struct OpenStream {
12
+ SDL_AudioStream *stream;
13
+ napi_env env;
14
+ };
15
+
16
+ static std::map<SDL_AudioDeviceID, OpenStream> open_streams;
10
17
 
11
18
  static SDL_AudioStream *
12
19
  _getStream (Napi::Env &env, SDL_AudioDeviceID audio_id)
@@ -17,7 +24,32 @@ _getStream (Napi::Env &env, SDL_AudioDeviceID audio_id)
17
24
  message << "getAudioStream(" << audio_id << ") error: invalid audio stream id";
18
25
  throw Napi::Error::New(env, message.str());
19
26
  }
20
- return entry->second;
27
+ return entry->second.stream;
28
+ }
29
+
30
+ void
31
+ audio::closeEnvStreams (Napi::Env env)
32
+ {
33
+ std::lock_guard<std::mutex> guard(global::lock());
34
+
35
+ for (auto it = open_streams.begin(); it != open_streams.end();) {
36
+ if (it->second.env == (napi_env) env) {
37
+ SDL_DestroyAudioStream(it->second.stream);
38
+ it = open_streams.erase(it);
39
+ }
40
+ else {
41
+ it++;
42
+ }
43
+ }
44
+ }
45
+
46
+ void
47
+ audio::closeAllStreams ()
48
+ {
49
+ for (auto &entry : open_streams) {
50
+ SDL_DestroyAudioStream(entry.second.stream);
51
+ }
52
+ open_streams.clear();
21
53
  }
22
54
 
23
55
 
@@ -82,6 +114,9 @@ audio::getDevices(const Napi::CallbackInfo &info)
82
114
  {
83
115
  Napi::Env env = info.Env();
84
116
 
117
+ std::lock_guard<std::mutex> guard(global::lock());
118
+ global::assertReady(env);
119
+
85
120
  bool is_recording = info[0].As<Napi::Boolean>().Value();
86
121
 
87
122
  return audio::_getDevices(env, is_recording);
@@ -92,6 +127,9 @@ audio::open (const Napi::CallbackInfo &info)
92
127
  {
93
128
  Napi::Env env = info.Env();
94
129
 
130
+ std::lock_guard<std::mutex> guard(global::lock());
131
+ global::assertReady(env);
132
+
95
133
  bool has_id = !info[0].IsNull();
96
134
  bool is_recording = info[1].As<Napi::Boolean>().Value();
97
135
  int freq = info[2].As<Napi::Number>().Int32Value();
@@ -132,7 +170,7 @@ audio::open (const Napi::CallbackInfo &info)
132
170
  throw Napi::Error::New(env, message.str());
133
171
  }
134
172
 
135
- open_streams[audio_id] = stream;
173
+ open_streams[audio_id] = { stream, env };
136
174
 
137
175
  return Napi::Number::New(env, audio_id);
138
176
  }
@@ -142,6 +180,9 @@ audio::getDeviceFormat (const Napi::CallbackInfo &info)
142
180
  {
143
181
  Napi::Env env = info.Env();
144
182
 
183
+ std::lock_guard<std::mutex> guard(global::lock());
184
+ global::assertReady(env);
185
+
145
186
  int audio_id = info[0].As<Napi::Number>().Int32Value();
146
187
 
147
188
  SDL_AudioSpec spec;
@@ -172,6 +213,9 @@ audio::play (const Napi::CallbackInfo &info)
172
213
  {
173
214
  Napi::Env env = info.Env();
174
215
 
216
+ std::lock_guard<std::mutex> guard(global::lock());
217
+ global::assertReady(env);
218
+
175
219
  int audio_id = info[0].As<Napi::Number>().Int32Value();
176
220
  bool should_play = info[1].As<Napi::Boolean>().Value();
177
221
 
@@ -195,6 +239,9 @@ audio::getQueued (const Napi::CallbackInfo &info)
195
239
  {
196
240
  Napi::Env env = info.Env();
197
241
 
242
+ std::lock_guard<std::mutex> guard(global::lock());
243
+ global::assertReady(env);
244
+
198
245
  int audio_id = info[0].As<Napi::Number>().Int32Value();
199
246
 
200
247
  SDL_AudioStream *stream = _getStream(env, audio_id);
@@ -215,6 +262,9 @@ audio::getAvailable (const Napi::CallbackInfo &info)
215
262
  {
216
263
  Napi::Env env = info.Env();
217
264
 
265
+ std::lock_guard<std::mutex> guard(global::lock());
266
+ global::assertReady(env);
267
+
218
268
  int audio_id = info[0].As<Napi::Number>().Int32Value();
219
269
 
220
270
  SDL_AudioStream *stream = _getStream(env, audio_id);
@@ -235,6 +285,9 @@ audio::clear (const Napi::CallbackInfo &info)
235
285
  {
236
286
  Napi::Env env = info.Env();
237
287
 
288
+ std::lock_guard<std::mutex> guard(global::lock());
289
+ global::assertReady(env);
290
+
238
291
  int audio_id = info[0].As<Napi::Number>().Int32Value();
239
292
 
240
293
  SDL_AudioStream *stream = _getStream(env, audio_id);
@@ -254,6 +307,9 @@ audio::putData (const Napi::CallbackInfo &info)
254
307
  {
255
308
  Napi::Env env = info.Env();
256
309
 
310
+ std::lock_guard<std::mutex> guard(global::lock());
311
+ global::assertReady(env);
312
+
257
313
  int audio_id = info[0].As<Napi::Number>().Int32Value();
258
314
  void *src = info[1].As<Napi::Buffer<char>>().Data();
259
315
  int size = info[2].As<Napi::Number>().Int32Value();
@@ -275,6 +331,9 @@ audio::getData (const Napi::CallbackInfo &info)
275
331
  {
276
332
  Napi::Env env = info.Env();
277
333
 
334
+ std::lock_guard<std::mutex> guard(global::lock());
335
+ global::assertReady(env);
336
+
278
337
  int audio_id = info[0].As<Napi::Number>().Int32Value();
279
338
  void *dst = info[1].As<Napi::Buffer<char>>().Data();
280
339
  int size = info[2].As<Napi::Number>().Int32Value();
@@ -297,6 +356,9 @@ audio::close (const Napi::CallbackInfo &info)
297
356
  {
298
357
  Napi::Env env = info.Env();
299
358
 
359
+ std::lock_guard<std::mutex> guard(global::lock());
360
+ global::assertReady(env);
361
+
300
362
  int audio_id = info[0].As<Napi::Number>().Int32Value();
301
363
 
302
364
  SDL_AudioStream *stream = _getStream(env, audio_id);
@@ -11,6 +11,9 @@ namespace audio {
11
11
  extern std::map<bool, std::string> device_types;
12
12
  extern std::map<SDL_AudioFormat, std::string> formats;
13
13
 
14
+ void closeEnvStreams(Napi::Env env);
15
+ void closeAllStreams();
16
+
14
17
  Napi::Value _getDevice(Napi::Env &env, SDL_AudioDeviceID id);
15
18
  Napi::Array _getDevices(Napi::Env &env, bool is_recording);
16
19
 
@@ -12,6 +12,7 @@
12
12
  #include <string>
13
13
  #include <sstream>
14
14
  #include <vector>
15
+ #include <atomic>
15
16
 
16
17
  #if defined(SDL_PLATFORM_MACOS)
17
18
  #include "cocoa-global.h"
@@ -19,6 +20,28 @@
19
20
 
20
21
 
21
22
  static SDL_ThreadID mainThreadId;
23
+ static std::atomic<bool> ready { false };
24
+
25
+ std::mutex &
26
+ global::lock()
27
+ {
28
+ static std::mutex mutex;
29
+ return mutex;
30
+ }
31
+
32
+ void
33
+ global::assertReady(Napi::Env &env)
34
+ {
35
+ if (!ready.load(std::memory_order_acquire)) {
36
+ throw Napi::Error::New(env, "SDL is not initialized, import @kmamal/sdl in the main thread first");
37
+ }
38
+ }
39
+
40
+ void
41
+ global::registerEnv(Napi::Env env)
42
+ {
43
+ env.AddCleanupHook([env]() { audio::closeEnvStreams(env); });
44
+ }
22
45
 
23
46
  bool watchEvents(void*, SDL_Event *event) {
24
47
  if (true
@@ -395,6 +418,8 @@ global::initialize(const Napi::CallbackInfo &info)
395
418
 
396
419
  SDL_memset(&joystick::zero_guid, 0, sizeof(joystick::zero_guid));
397
420
 
421
+ ready.store(true, std::memory_order_release);
422
+
398
423
  Napi::Object result = Napi::Object::New(env);
399
424
  result.Set("version", versions);
400
425
  result.Set("platform", platform);
@@ -410,6 +435,10 @@ global::cleanup(const Napi::CallbackInfo &info)
410
435
  {
411
436
  Napi::Env env = info.Env();
412
437
 
438
+ std::lock_guard<std::mutex> guard(global::lock());
439
+
440
+ audio::closeAllStreams();
441
+ ready.store(false, std::memory_order_release);
413
442
  SDL_Quit();
414
443
 
415
444
  return env.Undefined();
@@ -2,9 +2,14 @@
2
2
  #define _GLOBAL_H_
3
3
 
4
4
  #include <napi.h>
5
+ #include <mutex>
5
6
 
6
7
  namespace global {
7
8
 
9
+ std::mutex &lock();
10
+ void assertReady(Napi::Env &env);
11
+ void registerEnv(Napi::Env env);
12
+
8
13
  Napi::Value initialize(const Napi::CallbackInfo &info);
9
14
  Napi::Value cleanup(const Napi::CallbackInfo &info);
10
15
 
@@ -19,6 +19,8 @@
19
19
  Napi::Object
20
20
  init (Napi::Env env, Napi::Object exports)
21
21
  {
22
+ global::registerEnv(env);
23
+
22
24
  exports.Set("enums_get", Napi::Function::New<enums::get>(env));
23
25
 
24
26
  exports.Set("global_initialize", Napi::Function::New<global::initialize>(env));
@@ -625,10 +625,7 @@ export namespace Sdl {
625
625
 
626
626
  readonly opengl: boolean
627
627
  readonly webgpu: boolean
628
- readonly native: {
629
- readonly handle: Buffer | null,
630
- readonly subsystem: 'x11' | 'wayland' | null,
631
- }
628
+ readonly native: unknown
632
629
 
633
630
  readonly maximized: boolean
634
631
  maximize (): void
@@ -1,7 +1,6 @@
1
-
2
1
  import type { Sdl } from './index'
3
2
 
4
- export namespace SdlHelpers {
3
+ export namespace SdlWorker {
5
4
 
6
5
  export namespace Video {
7
6
 
@@ -52,14 +51,21 @@ export namespace SdlHelpers {
52
51
  zeroSampleValue (format: Format): number
53
52
  readSample (format: Format, buffer: Buffer, offset?: number): number
54
53
  writeSample (format: Format, buffer: Buffer, value: number, offset?: number): number
54
+
55
+ readonly playback: DeviceModule<Sdl.Audio.AudioPlaybackStream>
56
+ readonly recording: DeviceModule<Sdl.Audio.AudioRecordingStream>
57
+ }
58
+
59
+ interface DeviceModule<Stream extends Sdl.Audio.AudioStream> {
60
+ openDevice (device?: Sdl.Audio.Device | null, options?: Sdl.Audio.StreamOptions): Stream
55
61
  }
56
62
 
57
63
  }
58
64
 
59
65
  }
60
66
 
61
- export const video: SdlHelpers.Video.Module
62
- export const keyboard: SdlHelpers.Keyboard.Module
63
- export const mouse: SdlHelpers.Mouse.Module
64
- export const sensor: SdlHelpers.Sensor.Module
65
- export const audio: SdlHelpers.Audio.Module
67
+ export const video: SdlWorker.Video.Module
68
+ export const keyboard: SdlWorker.Keyboard.Module
69
+ export const mouse: SdlWorker.Mouse.Module
70
+ export const sensor: SdlWorker.Sensor.Module
71
+ export const audio: SdlWorker.Audio.Module