@kmamal/sdl 0.10.3 → 0.10.6

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.md CHANGED
@@ -115,7 +115,7 @@ renderer.swap()
115
115
 
116
116
  ### More examples
117
117
 
118
- Check the [`examples/`](https://github.com/kmamal/node-sdl/tree/master/examples) folder.
118
+ Check the [`examples/`](https://github.com/kmamal/node-sdl/tree/master/examples#readme) folder.
119
119
 
120
120
 
121
121
  # API Reference
@@ -310,9 +310,7 @@ Check the [`examples/`](https://github.com/kmamal/node-sdl/tree/master/examples)
310
310
  * [sdl.audio.maxSampleValue(format)](#sdlaudiomaxsamplevalueformat)
311
311
  * [sdl.audio.zeroSampleValue(format)](#sdlaudiozerosamplevalueformat)
312
312
  * [sdl.audio.readSample(format, buffer[, offset])](#sdlaudioreadsampleformat-buffer-offset)
313
- * [sdl.audio.readerName(format)](#sdlaudioreadernameformat)
314
313
  * [sdl.audio.writeSample(format, buffer, value[, offset])](#sdlaudiowritesampleformat-buffer-value-offset)
315
- * [sdl.audio.writerName(format)](#sdlaudiowriternameformat)
316
314
  * [sdl.audio.devices](#sdlaudiodevices)
317
315
  * [sdl.audio.openDevice(device[, options])](#sdlaudioopendevicedevice-options)
318
316
  * [class AudioInstance](#class-audioinstance)
@@ -326,9 +324,7 @@ Check the [`examples/`](https://github.com/kmamal/node-sdl/tree/master/examples)
326
324
  * [audioInstance.maxSampleValue](#audioinstancemaxsamplevalue)
327
325
  * [audioInstance.zeroSampleValue](#audioinstancezerosamplevalue)
328
326
  * [audioInstance.readSample(buffer[, offset])](#audioinstancereadsamplebuffer-offset)
329
- * [audioInstance.readerName](#audioinstancereadername)
330
327
  * [audioInstance.writeSample(buffer, value[, offset])](#audioinstancewritesamplebuffer-value-offset)
331
- * [audioInstance.writerName](#audioinstancewritername)
332
328
  * [audioInstance.buffered](#audioinstancebuffered)
333
329
  * [audioInstance.playing](#audioinstanceplaying)
334
330
  * [audioInstance.play([play])](#audioinstanceplayplay)
@@ -347,6 +343,7 @@ Check the [`examples/`](https://github.com/kmamal/node-sdl/tree/master/examples)
347
343
  * [sdl.clipboard.setText(text)](#sdlclipboardsettexttext)
348
344
  * [sdl.power](#sdlpower)
349
345
  * [sdl.power.info](#sdlpowerinfo)
346
+ * [helpers](#helpers)
350
347
 
351
348
 
352
349
  ## sdl
@@ -518,7 +515,7 @@ Check [`sdl.video.displays`](#sdlvideodisplays) to get the new list of displays.
518
515
  * `x, y, width, height: <Rect>` The position and size of the display's geometry.
519
516
  * `usable: <object>` Similar to `geometry`, but excludes areas taken up by the OS or window manager such as menus, docks, e.t.c.
520
517
  * `x, y, width, height: <Rect>` The position and size of the display's usable region.
521
- * `dpi: <object>` Return pixel density for the display in dots/pixels-per-inch units.
518
+ * `dpi: <object>|<null>` Return pixel density for the display in dots/pixels-per-inch units. Might be `null` on some devices if DPI info can't be retrieved.
522
519
  * `horizontal: <number>` The horizontal density.
523
520
  * `vertical: <number>` The vertical density.
524
521
  * `diagonal: <number>` The diagonal density.
@@ -2220,6 +2217,8 @@ When this event is emitted, all instances that were opened from the removed devi
2220
2217
 
2221
2218
  Helper function which maps each sample format to the corresponding number of bytes its samples take up.
2222
2219
 
2220
+ This function is also available from `@kmamal/sdl/helpers`.
2221
+
2223
2222
  ### sdl.audio.minSampleValue(format)
2224
2223
 
2225
2224
  * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
@@ -2227,6 +2226,8 @@ Helper function which maps each sample format to the corresponding number of byt
2227
2226
 
2228
2227
  Helper function which maps each sample format to the corresponding minimum value its samples can take.
2229
2228
 
2229
+ This function is also available from `@kmamal/sdl/helpers`.
2230
+
2230
2231
  ### sdl.audio.maxSampleValue(format)
2231
2232
 
2232
2233
  * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
@@ -2234,6 +2235,8 @@ Helper function which maps each sample format to the corresponding minimum value
2234
2235
 
2235
2236
  Helper function which maps each sample format to the corresponding maximum value its samples can take.
2236
2237
 
2238
+ This function is also available from `@kmamal/sdl/helpers`.
2239
+
2237
2240
  ### sdl.audio.zeroSampleValue(format)
2238
2241
 
2239
2242
  * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
@@ -2241,6 +2244,8 @@ Helper function which maps each sample format to the corresponding maximum value
2241
2244
 
2242
2245
  Helper function which maps each sample format to the sample value that corresponds to silence.
2243
2246
 
2247
+ This function is also available from `@kmamal/sdl/helpers`.
2248
+
2244
2249
  ### sdl.audio.readSample(format, buffer[, offset])
2245
2250
 
2246
2251
  * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
@@ -2251,14 +2256,7 @@ Helper function which maps each sample format to the sample value that correspon
2251
2256
  Helper function which calls the appropriate `read*` method of `Buffer` based on the format argument.
2252
2257
  For example, a call to `sdl.audio.readSample('f32', buffer, offset)` would be equivalent to `buffer.readFloatLE(offset)`.
2253
2258
 
2254
- ### sdl.audio.readerName(format)
2255
-
2256
- * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
2257
- * Returns: `<string>` The name of the read method.
2258
-
2259
- Helper function which returns the name of the appropriate `read*` method of `Buffer` based on the format argument.
2260
- Most of the time you will want to use [sdl.audio.readSample](#sdlaudioreadsampleformat-buffer-offset) directly.
2261
- The method name is only really useful for passing to worker threads.
2259
+ This function is also available from `@kmamal/sdl/helpers`.
2262
2260
 
2263
2261
  ### sdl.audio.writeSample(format, buffer, value[, offset])
2264
2262
 
@@ -2271,14 +2269,7 @@ The method name is only really useful for passing to worker threads.
2271
2269
  Helper function which calls the appropriate `write*` method of `Buffer` based on the format argument.
2272
2270
  For example, a call to `sdl.audio.writeSample('f32', buffer, value, offset)` would be equivalent to `buffer.writeFloatLE(value, offset)`.
2273
2271
 
2274
- ### sdl.audio.writerName(format)
2275
-
2276
- * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
2277
- * Returns: `<string>` The name of the write method.
2278
-
2279
- Helper function which returns the name of the appropriate `write*` method of `Buffer` based on the format argument.
2280
- Most of the time you will want to use [sdl.audio.writeSample](#sdlaudiowritesampleformat-buffer-value-offset) directly.
2281
- The method name is only really useful for passing to worker threads.
2272
+ This function is also available from `@kmamal/sdl/helpers`.
2282
2273
 
2283
2274
  ### sdl.audio.devices
2284
2275
 
@@ -2411,14 +2402,6 @@ The sample value that corresponds to silence, based on the format the instance w
2411
2402
  Helper function which calls the appropriate `read*` method of `Buffer` based on the format the instance was opened with.
2412
2403
  For example, for an instance opened with the `'f32'` sample format, a call to `audioinstance.readSample(buffer, offset)` would be equivalent to `buffer.readFloatLE(offset)`.
2413
2404
 
2414
- ### audioInstance.readerName
2415
-
2416
- * `<string>`
2417
-
2418
- The name of the appropriate `read*` method of `Buffer` based on the format the instance was opened with.
2419
- Most of the time you will want to use [audioInstance.readSample](#audioinstancereadsamplebuffer-offset) directly.
2420
- The method name is only really useful for passing to worker threads.
2421
-
2422
2405
  ### audioInstance.writeSample(buffer, value[, offset])
2423
2406
 
2424
2407
  * `buffer: <Buffer>` The buffer to write the sample to.
@@ -2429,14 +2412,6 @@ The method name is only really useful for passing to worker threads.
2429
2412
  Helper function which calls the appropriate `write*` method of `Buffer` based on the format the instance was opened with.
2430
2413
  For example, for an instance opened with the `'f32'` sample format, a call to `audioinstance.writeSample(buffer, value, offset)` would be equivalent to `buffer.writeFloatLE(value, offset)`.
2431
2414
 
2432
- ### audioInstance.writerName
2433
-
2434
- * `<string>`
2435
-
2436
- The name of the appropriate `write*` method of `Buffer` based on the format the instance was opened with.
2437
- Most of the time you will want to use [audioInstance.writeSample](#audioinstancewritesamplebuffer-value-offset) directly.
2438
- The method name is only really useful for passing to worker threads.
2439
-
2440
2415
  ### audioInstance.buffered
2441
2416
 
2442
2417
  * `<number>`
@@ -2540,6 +2515,26 @@ Changes the text contents of the clipboard.
2540
2515
  The curent power information of the device.
2541
2516
 
2542
2517
 
2518
+ ## Helpers
2519
+
2520
+ The `@kmamal/sdl` library can only be imported from the main thread.
2521
+ If you try importing it from a `worker_thread` you will get an error.
2522
+ This is mainly due to some limitations in SDL itself (it's often unsafe to call functions from threads other than the one that called `SDL_Init`) as well as Node.js native modules (each thread gets it's own instance of the module and it's hard to make them talk with each other).
2523
+
2524
+ It's often useful however to offload CPU-heavy work to a thread, so the main thread can respond to input events faster.
2525
+ This is still possible! Even if the threads do not have access to the SDL-related functions, they can still write data to buffers and then pass those buffers to the main thread from where they can be passed to SDL. One thing is missing: While the core of the library is not needed, it's nice to have the helper functions, for example when writing an audio renderer it's nice to have the [`readSample`](#sdlaudioreadsampleformat-buffer-offset), [`writeSample`](#sdlaudiowritesampleformat-buffer-value-offset), etc functions.
2526
+
2527
+ Since these are just helpers and don't call any SLD code underneath it's safe to use them. They are made available through the `@kmamal/sdl/helpers` sub-module that does not load any of the native code. For an example of their use see [this example](https://github.com/kmamal/node-sdl/blob/master/examples/12-audio-thread/audio-worker.js).
2528
+
2529
+ The functions included in `@kmamal/sdl/helpers` are:
2530
+ - [`sdl.audio.bytesPerSample`](#sdlaudiobytespersampleformat)
2531
+ - [`sdl.audio.minSampleValue`](#sdlaudiominsamplevalueformat)
2532
+ - [`sdl.audio.maxSampleValue`](#sdlaudiomaxsamplevalueformat)
2533
+ - [`sdl.audio.zeroSampleValue`](#sdlaudiozerosamplevalueformat)
2534
+ - [`sdl.audio.readSample`](#sdlaudioreadsampleformat-buffer-offset)
2535
+ - [`sdl.audio.writeSample`](#sdlaudiowritesampleformat-buffer-value-offset)
2536
+
2537
+
2543
2538
  ## Building from source
2544
2539
 
2545
2540
  If there are no prebuilt binaries available for your platform, `@kmamal/sdl` will try to compile itself during installation.
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "0.10.3",
2
+ "version": "0.10.6",
3
3
  "name": "@kmamal/sdl",
4
4
  "description": "SDL bindings for Node.js",
5
5
  "keywords": [
@@ -42,6 +42,10 @@
42
42
  ".": {
43
43
  "types": "./src/types/index.d.ts",
44
44
  "default": "./src/javascript/index.js"
45
+ },
46
+ "./helpers": {
47
+ "types": "./src/types/helpers.d.ts",
48
+ "default": "./src/javascript/helpers.js"
45
49
  }
46
50
  },
47
51
  "gypfile": true,
@@ -56,7 +60,7 @@
56
60
  "clean": "cd scripts && node clean.mjs"
57
61
  },
58
62
  "dependencies": {
59
- "tar": "^6.2.0"
63
+ "tar": "^7.1.0"
60
64
  },
61
65
  "sdl": {
62
66
  "owner": "kmamal",
@@ -66,8 +70,8 @@
66
70
  "devDependencies": {
67
71
  "@kmamal/evdev": "^0.0.1",
68
72
  "@kmamal/testing": "^0.0.30",
69
- "@types/node": "^20.11.20",
70
- "node-addon-api": "^7.1.0",
71
- "node-gyp": "^10.0.1"
73
+ "@types/node": "^20.12.8",
74
+ "node-addon-api": "^8.0.0",
75
+ "node-gyp": "^10.1.0"
72
76
  }
73
77
  }
@@ -3,7 +3,7 @@ import Path from 'node:path'
3
3
  import { once } from 'node:events'
4
4
  import C from './util/common.js'
5
5
  import { fetch } from './util/fetch.js'
6
- import Tar from 'tar'
6
+ import * as Tar from 'tar'
7
7
 
8
8
  const url = `https://github.com/${C.sdl.owner}/${C.sdl.repo}/archive/refs/tags/v${C.sdl.version}.tar.gz`
9
9
 
@@ -2,7 +2,7 @@ import Fs from 'node:fs'
2
2
  import { once } from 'node:events'
3
3
  import C from './util/common.js'
4
4
  import { fetch } from './util/fetch.js'
5
- import Tar from 'tar'
5
+ import * as Tar from 'tar'
6
6
 
7
7
  const url = `https://github.com/${C.owner}/${C.repo}/releases/download/v${C.version}/${C.assetName}`
8
8
 
@@ -2,16 +2,22 @@ import Fs from 'node:fs'
2
2
  import { once } from 'node:events'
3
3
  import C from './util/common.js'
4
4
  import { fetch } from './util/fetch.js'
5
- import Tar from 'tar'
5
+ import * as Tar from 'tar'
6
6
 
7
7
  const url = `https://github.com/${C.sdl.owner}/${C.sdl.repo}/releases/download/v${C.sdl.version}/${C.sdl.assetName}`
8
8
 
9
9
  console.log("fetch", url)
10
- const response = await fetch(url)
10
+ try {
11
+ const response = await fetch(url)
11
12
 
12
- console.log("unpack to", C.dir.sdl)
13
- await Fs.promises.rm(C.dir.sdl, { recursive: true }).catch(() => {})
14
- await Fs.promises.mkdir(C.dir.sdl, { recursive: true })
15
- const tar = Tar.extract({ gzip: true, C: C.dir.sdl })
16
- response.stream().pipe(tar)
17
- await once(tar, 'finish')
13
+
14
+ console.log("unpack to", C.dir.sdl)
15
+ await Fs.promises.rm(C.dir.sdl, { recursive: true }).catch(() => {})
16
+ await Fs.promises.mkdir(C.dir.sdl, { recursive: true })
17
+ const tar = Tar.extract({ gzip: true, C: C.dir.sdl })
18
+ response.stream().pipe(tar)
19
+ await once(tar, 'finish')
20
+ } catch (error) {
21
+ console.log(error)
22
+ throw error
23
+ }
@@ -50,8 +50,6 @@ class AudioInstance extends EventsViaPoll {
50
50
  this._minSampleValue = helper.minSampleValue
51
51
  this._maxSampleValue = helper.maxSampleValue
52
52
  this._zeroSampleValue = helper.zeroSampleValue
53
- this._readerName = helper.readerName
54
- this._writerName = helper.writerName
55
53
  this._reader = helper.reader
56
54
  this._writer = helper.writer
57
55
 
@@ -75,14 +73,10 @@ class AudioInstance extends EventsViaPoll {
75
73
  return this._reader.call(buffer, offset)
76
74
  }
77
75
 
78
- get readerName () { return this._readerName }
79
-
80
76
  writeSample (buffer, value, offset) {
81
77
  return this._writer.call(buffer, value, offset)
82
78
  }
83
79
 
84
- get writerName () { return this._writerName }
85
-
86
80
  get buffered () { return this._buffered }
87
81
 
88
82
  get playing () { return this._playing }
@@ -23,53 +23,53 @@ const floatLimits = {
23
23
 
24
24
  const AudioFormatHelpers = {
25
25
  s8: {
26
- readerName: 'readInt8',
27
- writerName: 'writeInt8',
26
+ reader: Buffer.prototype.readInt8,
27
+ writer: Buffer.prototype.writeInt8,
28
28
  ...signedLimits(8),
29
29
  },
30
30
  u8: {
31
- readerName: 'readUInt8',
32
- writerName: 'writeUInt8',
31
+ reader: Buffer.prototype.readUInt8,
32
+ writer: Buffer.prototype.writeUInt8,
33
33
  ...unsignedLimits(8),
34
34
  },
35
35
  s16lsb: {
36
- readerName: 'readInt16LE',
37
- writerName: 'writeInt16LE',
36
+ reader: Buffer.prototype.readInt16LE,
37
+ writer: Buffer.prototype.writeInt16LE,
38
38
  ...signedLimits(16),
39
39
  },
40
40
  s16msb: {
41
- readerName: 'readInt16BE',
42
- writerName: 'writeInt16BE',
41
+ reader: Buffer.prototype.readInt16BE,
42
+ writer: Buffer.prototype.writeInt16BE,
43
43
  ...signedLimits(16),
44
44
  },
45
45
  u16lsb: {
46
- readerName: 'readUInt16LE',
47
- writerName: 'writeUInt16LE',
46
+ reader: Buffer.prototype.readUInt16LE,
47
+ writer: Buffer.prototype.writeUInt16LE,
48
48
  ...unsignedLimits(16),
49
49
  },
50
50
  u16msb: {
51
- readerName: 'readUInt16BE',
52
- writerName: 'writeUInt16BE',
51
+ reader: Buffer.prototype.readUInt16BE,
52
+ writer: Buffer.prototype.writeUInt16BE,
53
53
  ...unsignedLimits(16),
54
54
  },
55
55
  s32lsb: {
56
- readerName: 'readInt32LE',
57
- writerName: 'writeInt32LE',
56
+ reader: Buffer.prototype.readInt32LE,
57
+ writer: Buffer.prototype.writeInt32LE,
58
58
  ...signedLimits(32),
59
59
  },
60
60
  s32msb: {
61
- readerName: 'readInt32BE',
62
- writerName: 'writeInt32BE',
61
+ reader: Buffer.prototype.readInt32BE,
62
+ writer: Buffer.prototype.writeInt32BE,
63
63
  ...signedLimits(32),
64
64
  },
65
65
  f32lsb: {
66
- readerName: 'readFloatLE',
67
- writerName: 'writeFloatLE',
66
+ reader: Buffer.prototype.readFloatLE,
67
+ writer: Buffer.prototype.writeFloatLE,
68
68
  ...floatLimits,
69
69
  },
70
70
  f32msb: {
71
- readerName: 'readFloatBE',
72
- writerName: 'writeFloatBE',
71
+ reader: Buffer.prototype.readFloatBE,
72
+ writer: Buffer.prototype.writeFloatBE,
73
73
  ...floatLimits,
74
74
  },
75
75
  }
@@ -91,9 +91,4 @@ if (Os.endianness() === 'LE') {
91
91
  AudioFormatHelpers.f32sys = AudioFormatHelpers.f32msb
92
92
  }
93
93
 
94
- for (const helper of Object.values(AudioFormatHelpers)) {
95
- helper.reader = Buffer.prototype[helper.readerName]
96
- helper.writer = Buffer.prototype[helper.writerName]
97
- }
98
-
99
94
  module.exports = { AudioFormatHelpers }
@@ -44,17 +44,9 @@ const audio = new class extends EventsViaPoll {
44
44
  return AudioFormatHelpers[format].reader.call(buffer, offset)
45
45
  }
46
46
 
47
- readerName (format) {
48
- return AudioFormatHelpers[format].readerName
49
- }
50
-
51
47
  writeSample (format, buffer, value, offset) {
52
48
  return AudioFormatHelpers[format].writer.call(buffer, value, offset)
53
49
  }
54
-
55
- writerName (format) {
56
- return AudioFormatHelpers[format].writerName
57
- }
58
50
  }()
59
51
 
60
52
  module.exports = { audio }
@@ -0,0 +1,18 @@
1
+ const { AudioFormatHelpers } = require('./audio/format-helpers')
2
+
3
+ module.exports = {
4
+ audio: {
5
+ bytesPerSample (format) { return AudioFormatHelpers[format].bytesPerSample },
6
+ minSampleValue (format) { return AudioFormatHelpers[format].minSampleValue },
7
+ maxSampleValue (format) { return AudioFormatHelpers[format].maxSampleValue },
8
+ zeroSampleValue (format) { return AudioFormatHelpers[format].zeroSampleValue },
9
+
10
+ readSample (format, buffer, offset) {
11
+ return AudioFormatHelpers[format].reader.call(buffer, offset)
12
+ },
13
+
14
+ writeSample (format, buffer, value, offset) {
15
+ return AudioFormatHelpers[format].writer.call(buffer, value, offset)
16
+ },
17
+ },
18
+ }
@@ -67,19 +67,18 @@ video::getDisplays(const Napi::CallbackInfo &info)
67
67
  usable.Set("width", Napi::Number::New(env, rect.w));
68
68
  usable.Set("height", Napi::Number::New(env, rect.h));
69
69
 
70
+ Napi::Value dpi;
70
71
  float ddpi, hdpi, vdpi;
71
72
  if (SDL_GetDisplayDPI(i, &ddpi, &hdpi, &vdpi) < 0) {
72
- std::ostringstream message;
73
- message << "SDL_GetDisplayDPI(" << i << ") error: " << SDL_GetError();
74
- SDL_ClearError();
75
- throw Napi::Error::New(env, message.str());
73
+ dpi = env.Null();
74
+ } else {
75
+ Napi::Object dpi_obj = Napi::Object::New(env);
76
+ dpi_obj.Set("diagonal", Napi::Number::New(env, ddpi));
77
+ dpi_obj.Set("horizontal", Napi::Number::New(env, hdpi));
78
+ dpi_obj.Set("vertical", Napi::Number::New(env, vdpi));
79
+ dpi = dpi_obj;
76
80
  }
77
81
 
78
- Napi::Object dpi = Napi::Object::New(env);
79
- dpi.Set("diagonal", Napi::Number::New(env, ddpi));
80
- dpi.Set("horizontal", Napi::Number::New(env, hdpi));
81
- dpi.Set("vertical", Napi::Number::New(env, vdpi));
82
-
83
82
  Napi::Object display = Napi::Object::New(env);
84
83
  display.Set("name", Napi::String::New(env, name));
85
84
  display.Set("format", video::formats[(SDL_PixelFormatEnum) mode.format]);
@@ -0,0 +1,39 @@
1
+
2
+ export namespace SdlHelpers {
3
+
4
+ export namespace Audio {
5
+
6
+ export type Format
7
+ = 's8'
8
+ | 'u8'
9
+ | 's16lsb'
10
+ | 's16msb'
11
+ | 's16sys'
12
+ | 's16'
13
+ | 'u16lsb'
14
+ | 'u16msb'
15
+ | 'u16sys'
16
+ | 'u16'
17
+ | 's32lsb'
18
+ | 's32msb'
19
+ | 's32sys'
20
+ | 's32'
21
+ | 'f32lsb'
22
+ | 'f32msb'
23
+ | 'f32sys'
24
+ | 'f32'
25
+
26
+ interface Module {
27
+ bytesPerSample (format: Format): number
28
+ minSampleValue (format: Format): number
29
+ maxSampleValue (format: Format): number
30
+ zeroSampleValue (format: Format): number
31
+ readSample (format: Format, buffer: Buffer, offset?: number): number
32
+ writeSample (format: Format, buffer: Buffer, value: number, offset?: number): number
33
+ }
34
+
35
+ }
36
+
37
+ }
38
+
39
+ export const audio: SdlHelpers.Audio.Module
@@ -371,7 +371,7 @@ export namespace Sdl {
371
371
  readonly horizontal: number
372
372
  readonly vertical: number
373
373
  readonly diagonal: number
374
- }
374
+ } | null
375
375
  }
376
376
 
377
377
  export class Window {