@kmamal/sdl 0.10.11 → 0.10.12

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
@@ -25,7 +25,7 @@ SDL is bundled along with the binaries so a separate installation is not necessa
25
25
  This package is self-contained.
26
26
  Just run:
27
27
 
28
- ```
28
+ ```bash
29
29
  npm install @kmamal/sdl
30
30
  ```
31
31
 
@@ -44,6 +44,7 @@ window.on('*', console.log)
44
44
  ```
45
45
 
46
46
  ### Canvas
47
+
47
48
  ```js
48
49
  import sdl from '@kmamal/sdl'
49
50
  import { createCanvas } from 'canvas'
@@ -64,6 +65,7 @@ window.render(width, height, width * 4, 'bgra32', buffer)
64
65
  ```
65
66
 
66
67
  ### WebGL
68
+
67
69
  ```js
68
70
  import sdl from '@kmamal/sdl'
69
71
  import createContext from '@kmamal/gl'
@@ -82,6 +84,7 @@ gl.swap()
82
84
  ```
83
85
 
84
86
  ### WebGPU
87
+
85
88
  ```js
86
89
  import sdl from '@kmamal/sdl'
87
90
  import gpu from '@kmamal/gpu'
@@ -203,7 +206,7 @@ Check the [`examples/`](https://github.com/kmamal/node-sdl/tree/master/examples#
203
206
  * [window.popupMenu](#windowpopupmenu)
204
207
  * [window.tooltip](#windowtooltip)
205
208
  * [window.utility](#windowutility)
206
- * [window.render(width, height, stride, format, buffer)](#windowrenderwidth-height-stride-format-buffer)
209
+ * [window.render(width, height, stride, format, buffer[, scaling])](#windowrenderwidth-height-stride-format-buffer-scaling)
207
210
  * [window.setIcon(width, height, stride, format, buffer)](#windowseticonwidth-height-stride-format-buffer)
208
211
  * [window.flash(untilFocused)](#windowflashuntilfocused)
209
212
  * [window.stopFlashing()](#windowstopflashing)
@@ -231,6 +234,7 @@ Check the [`examples/`](https://github.com/kmamal/node-sdl/tree/master/examples#
231
234
  * [sdl.mouse.uncapture()](#sdlmouseuncapture)
232
235
  * [sdl.joystick](#sdljoystick)
233
236
  * [Hat positions](#hat-positions)
237
+ * [Power levels](#power-levels)
234
238
  * [Event: 'deviceAdd'](#joystick-event-deviceadd)
235
239
  * [Event: 'deviceRemove'](#joystick-event-deviceremove)
236
240
  * [sdl.joystick.devices](#sdljoystickdevices)
@@ -340,7 +344,7 @@ Check the [`examples/`](https://github.com/kmamal/node-sdl/tree/master/examples#
340
344
  * [class AudioRecordingInstance extends AudioInstance](#class-audiorecordinginstance-extends-audioinstance)
341
345
  * [recordingInstance.dequeue(buffer[, bytes])](#recordinginstancedequeuebuffer-bytes)
342
346
  * [sdl.clipboard](#sdlclipboard)
343
- * [Event: 'update'](#event-update)
347
+ * [Event: 'update'](#clipboard-event-update)
344
348
  * [sdl.clipboard.text](#sdlclipboardtext)
345
349
  * [sdl.clipboard.setText(text)](#sdlclipboardsettexttext)
346
350
  * [sdl.power](#sdlpower)
@@ -402,11 +406,13 @@ Sample data for Ubuntu:
402
406
  ### Image data
403
407
 
404
408
  There are 3 places in the API where you will need to provide an image to the library:
405
- * [`window.render()`](#windowrenderwidth-height-stride-format-buffer)
409
+
410
+ * [`window.render()`](#windowrenderwidth-height-stride-format-buffer-scaling)
406
411
  * [`window.setIcon()`](#windowseticonwidth-height-stride-format-buffer)
407
412
  * [`mouse.setCursorImage()`](#sdlmousesetcursorimagewidth-height-stride-format-buffer-x-y)
408
413
 
409
414
  All three of these functions accept the image as a series of arguments:
415
+
410
416
  * `width: <number>` The width of the image in pixels.
411
417
  * `height: <number>` The height of the image in pixels.
412
418
  * `stride: <number>` How many bytes each row of the image takes up in the buffer. This is usually equal to `width * bytesPerPixel`, but can be larger if the rows of the buffer are padded to always be some multiple of bytes.
@@ -592,6 +598,7 @@ The window that the mouse is hovered over, or `null` if the mouse is not over a
592
598
  Creates a new window.
593
599
 
594
600
  The following restrictions apply:
601
+
595
602
  * If you specify the `display` option, you can't also specify the `x` or `y` options, and vice-versa.
596
603
  * The `resizable` and `borderless` options are mutually exclusive.
597
604
  * The `opengl` and `webgpu` options are mutually exclusive.
@@ -599,7 +606,7 @@ The following restrictions apply:
599
606
  * The `accelerated` and `vsync` options have no effect if either `opengl` or `webgpu` is also specified.
600
607
 
601
608
  If you set the `opengl` or `webgpu` options, then you can only render to the window with OpenGL/WebGPU calls.
602
- Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer) will fail.
609
+ Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-scaling) will fail.
603
610
 
604
611
  ## class Window
605
612
 
@@ -941,7 +948,7 @@ If you have set the `opengl` or `webgpu` options, then calls to this function wi
941
948
 
942
949
  Will be `true` if the window was created in OpenGl mode.
943
950
  In OpenGL mode, you can only render to the window with OpenGL calls.
944
- Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer) will fail.
951
+ Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-scaling) will fail.
945
952
 
946
953
  ### window.webgpu
947
954
 
@@ -949,7 +956,7 @@ Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer) will fail.
949
956
 
950
957
  Will be `true` if the window was created in WebGPU mode.
951
958
  In WebGPU mode, you can only render to the window with WebGPU calls.
952
- Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer) will fail.
959
+ Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-scaling) will fail.
953
960
 
954
961
  ### window.native
955
962
 
@@ -1030,15 +1037,24 @@ X11 only.
1030
1037
  Will be `true` if the window was created with `utility: true`.
1031
1038
  Such a window will always be treated as a utility window.
1032
1039
 
1033
- ### window.render(width, height, stride, format, buffer)
1040
+ ### window.render(width, height, stride, format, buffer[, scaling])
1034
1041
 
1035
1042
  * `width, height, stride, format, buffer: `[`<Image>`](#image-data) The image to display on the window.
1043
+ * `scaling: <string>` How to scale the image to match the window size. Default `'nearest'`
1036
1044
 
1037
1045
  Displays an image in the window.
1038
- The provided image will be stretched over the entire window.
1046
+ If the dimensions of the image do not match the dimansions of the window, then the image will be stretched over the entire surface of the window.
1047
+ The `scaling` argument controls how exactly the scaling is implemented.
1048
+ Possible values are:
1049
+
1050
+ | Value | Corresponding `SDL_ScaleMode` | Description |
1051
+ | --- | --- | --- |
1052
+ | `'nearest'` | `SDL_ScaleModeNearest` | nearest pixel sampling |
1053
+ | `'linear'` | `SDL_ScaleModeLinear` | linear filtering |
1054
+ | `'best'` | `SDL_ScaleModeBest` | anisotropic filtering |
1039
1055
 
1040
1056
  If you set the `opengl` or `webgpu` options, then you can only render to the window with OpenGL/WebGPU calls.
1041
- Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer) will fail.
1057
+ Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-scaling) will fail.
1042
1058
 
1043
1059
  ### window.setIcon(width, height, stride, format, buffer)
1044
1060
 
@@ -1116,6 +1132,7 @@ The same key will always produce the same scancode.
1116
1132
  Values are based on the [USB usage page standard](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf).
1117
1133
 
1118
1134
  <details>
1135
+
1119
1136
  <summary>Click to expand table</summary>
1120
1137
 
1121
1138
  | Value | Corresponding `SDL_Scancode` | Comment |
@@ -1362,6 +1379,7 @@ Values are based on the [USB usage page standard](https://www.usb.org/sites/defa
1362
1379
  | `sdl.keyboard.SCANCODE.APP2` | `SDL_SCANCODE_APP2` | |
1363
1380
  | `sdl.keyboard.SCANCODE.AUDIOREWIND` | `SDL_SCANCODE_AUDIOREWIND` | |
1364
1381
  | `sdl.keyboard.SCANCODE.AUDIOFASTFORWARD` | `SDL_SCANCODE_AUDIOFASTFORWARD` | |
1382
+
1365
1383
  </details>
1366
1384
 
1367
1385
  ### sdl.keyboard.getKey(scancode)
@@ -1503,6 +1521,19 @@ String values used to represent the positions of a joystick hat
1503
1521
  | `'leftup'` | `SDL_HAT_LEFTUP` |
1504
1522
  | `'leftdown'` | `SDL_HAT_LEFTDOWN` |
1505
1523
 
1524
+ ### Power levels
1525
+
1526
+ String values used to represent the power level of a joystick or controller
1527
+
1528
+ | Value | Corresponding `SDL_JoystickPowerLevel` |
1529
+ | --- | --- |
1530
+ | `'empty'` | `SDL_JOYSTICK_POWER_EMPTY` |
1531
+ | `'low'` | `SDL_JOYSTICK_POWER_LOW` |
1532
+ | `'medium'` | `SDL_JOYSTICK_POWER_MEDIUM` |
1533
+ | `'full'` | `SDL_JOYSTICK_POWER_FULL` |
1534
+ | `'wired'` | `SDL_JOYSTICK_POWER_WIRED` |
1535
+ | `'max'` | `SDL_JOYSTICK_POWER_MAX` |
1536
+
1506
1537
  <a id="joystick-event-deviceadd"></a>
1507
1538
 
1508
1539
  ### Event: 'deviceAdd'
@@ -1677,21 +1708,10 @@ An array of values, each corresponding to the position of one of the joystick's
1677
1708
 
1678
1709
  ### joystickInstance.power
1679
1710
 
1680
- * `<PowerLevel>|<null>`
1711
+ * [`<PowerLevel>`](#power-levels)`|<null>`
1681
1712
 
1682
1713
  The current power level of the joystick device, or `null` if it is unknown.
1683
1714
 
1684
- Possible values are:
1685
-
1686
- | Value | Corresponding `SDL_JoystickPowerLevel` |
1687
- | --- | --- |
1688
- | `'empty'` | `SDL_JOYSTICK_POWER_EMPTY` |
1689
- | `'low'` | `SDL_JOYSTICK_POWER_LOW` |
1690
- | `'medium'` | `SDL_JOYSTICK_POWER_MEDIUM` |
1691
- | `'full'` | `SDL_JOYSTICK_POWER_FULL` |
1692
- | `'wired'` | `SDL_JOYSTICK_POWER_WIRED` |
1693
- | `'max'` | `SDL_JOYSTICK_POWER_MAX` |
1694
-
1695
1715
  ### joystickInstance.setPlayer(index)
1696
1716
 
1697
1717
  * `index: <number>` The player index to assign to the joystick.
@@ -1781,6 +1801,7 @@ A mapping is a string that consists of the device's name, it's GUID, and a serie
1781
1801
  See the sample output [`here`](#sdlcontrollerdevices) for an example.
1782
1802
  SDL has pretty good default controller mappings, but if you need more, there's a community sourced database available on https://github.com/gabomdq/SDL_GameControllerDB.
1783
1803
  You can add them via:
1804
+
1784
1805
  ```js
1785
1806
  const url = 'https://raw.githubusercontent.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt'
1786
1807
  const result = await fetch(url)
@@ -1956,9 +1977,9 @@ The values will be `true` for buttons that are pressed and `false` otherwise.
1956
1977
 
1957
1978
  ### controllerInstance.power
1958
1979
 
1959
- * [`<PowerLevel>`](#power-levels)
1980
+ * [`<PowerLevel>`](#power-levels)`|<null>`
1960
1981
 
1961
- The current power level of the controller device.
1982
+ The current power level of the joystick device, or `null` if it is unknown.
1962
1983
 
1963
1984
  ### controllerInstance.setPlayer(index)
1964
1985
 
@@ -2075,7 +2096,7 @@ Instead, objects returned by [`sdl.sensor.openDevice()`](#sdlsensoropendevicedev
2075
2096
  ### Event: 'update'
2076
2097
 
2077
2098
  Fired when the sensor's data changes.
2078
- Get the new data by accessing [`sensorInstance.data`](#sensorInstancedata)
2099
+ Get the new data by accessing [`sensorInstance.data`](#sensorinstancedata)
2079
2100
 
2080
2101
  <a id="sensor-instance-event-close"></a>
2081
2102
 
@@ -2093,7 +2114,7 @@ The [device](#sdlsensordevices) from which this instance was opened.
2093
2114
  ### sensorInstance.data
2094
2115
 
2095
2116
  * `<object>`
2096
- * `timestamp: <number>|<null>` The time this measurement was taken **in microseconds**, or `null` if that's not available.
2117
+ * `timestamp: <number>|<null>` The time this measurement was taken __in microseconds__, or `null` if that's not available.
2097
2118
  * `x: <number>` X axis value.
2098
2119
  * `y: <number>` Y axis value.
2099
2120
  * `z: <number>` Z axis value.
@@ -2135,6 +2156,7 @@ An audio buffer is a sequence of frames, and each frame is a sequence of samples
2135
2156
  A _sample_ is a single number representing the intensity of an audio channel at a point in time.
2136
2157
  For audio with multiple channels, each point in time is represented by multiple samples (one per channel) that together make up a _frame_.
2137
2158
  The samples in a frame are arranged as follows:
2159
+
2138
2160
  * For 1 channel (mono) a frame contains just the one sample.
2139
2161
  * For 2 channels (stereo) the frame's first sample will be the one for the left channel, followed by the one for the right channel.
2140
2162
  * For 4 channels (quad) the layout is front-left, front-right, rear-left, rear-right.
@@ -2500,6 +2522,8 @@ Takes recorded audio data that has been put on the queue, and writes it to the p
2500
2522
 
2501
2523
  ## sdl.clipboard
2502
2524
 
2525
+ <a id="clipboard-event-update"></a>
2526
+
2503
2527
  ### Event: 'update'
2504
2528
 
2505
2529
  Fired when the contents of the clipboard have changed.
@@ -2523,7 +2547,7 @@ Changes the text contents of the clipboard.
2523
2547
  ### sdl.power.info
2524
2548
 
2525
2549
  * `<object>`
2526
- * `state: <string>|null` One of `'noBattery'`, `'battery'`, `'charging'`, `'charged'`. Will be `null` if it can't be determinded.
2550
+ * `state: <string>|<null>` One of `'noBattery'`, `'battery'`, `'charging'`, `'charged'`. Will be `null` if it can't be determinded.
2527
2551
  * `seconds: <number>|<null>` Seconds of battery life left. Will be `null` if not running on battery, or if it can't be determinded.
2528
2552
  * `percent: <number>|<null>` Percentage of battery life left. Will be `null` if not running on battery, or if it can't be determinded.
2529
2553
 
@@ -2542,12 +2566,13 @@ This is still possible! Even if the threads do not have access to the SDL-relate
2542
2566
  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).
2543
2567
 
2544
2568
  The functions included in `@kmamal/sdl/helpers` are:
2545
- - [`sdl.audio.bytesPerSample`](#sdlaudiobytespersampleformat)
2546
- - [`sdl.audio.minSampleValue`](#sdlaudiominsamplevalueformat)
2547
- - [`sdl.audio.maxSampleValue`](#sdlaudiomaxsamplevalueformat)
2548
- - [`sdl.audio.zeroSampleValue`](#sdlaudiozerosamplevalueformat)
2549
- - [`sdl.audio.readSample`](#sdlaudioreadsampleformat-buffer-offset)
2550
- - [`sdl.audio.writeSample`](#sdlaudiowritesampleformat-buffer-value-offset)
2569
+
2570
+ * [`sdl.audio.bytesPerSample`](#sdlaudiobytespersampleformat)
2571
+ * [`sdl.audio.minSampleValue`](#sdlaudiominsamplevalueformat)
2572
+ * [`sdl.audio.maxSampleValue`](#sdlaudiomaxsamplevalueformat)
2573
+ * [`sdl.audio.zeroSampleValue`](#sdlaudiozerosamplevalueformat)
2574
+ * [`sdl.audio.readSample`](#sdlaudioreadsampleformat-buffer-offset)
2575
+ * [`sdl.audio.writeSample`](#sdlaudiowritesampleformat-buffer-value-offset)
2551
2576
 
2552
2577
 
2553
2578
  ## Building from source
@@ -2569,6 +2594,7 @@ You will need to have `cmake` installed for that to work.
2569
2594
 
2570
2595
  You could also have found your way to the "Building from source" section because you are trying to contribute to this package.
2571
2596
  There are some npm scripts in `package.json` that could be of use to you:
2597
+
2572
2598
  * `npm run clean` deletes all folders that are created during the build, as well as `node_modules`.
2573
2599
  * `npm run download-release` downloads the prebuilt binaries. This is the first thing the install script tries to do.
2574
2600
  * `npm run download-sdl` downloads the SDL headers and libraries from `@kmamal/build-sdl` so you can compile against them in later steps. This is the second step in the install script, after `download-release` has failed.
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "0.10.11",
2
+ "version": "0.10.12",
3
3
  "name": "@kmamal/sdl",
4
4
  "description": "SDL bindings for Node.js",
5
5
  "keywords": [
@@ -357,7 +357,7 @@ class Window extends EventsViaPoll {
357
357
  get tooltip () { return this._tooltip }
358
358
  get utility () { return this._utility }
359
359
 
360
- render (width, height, stride, format, buffer) {
360
+ render (width, height, stride, format, buffer, scaling = 'nearest') {
361
361
  if (this._destroyed) { throw Object.assign(new Error("window is destroyed"), { id: this._id }) }
362
362
 
363
363
  if (this._opengl) { throw new Error("can't call render in opengl mode") }
@@ -372,11 +372,15 @@ class Window extends EventsViaPoll {
372
372
  if (typeof format !== 'string') { throw Object.assign(new Error("format must be a string"), { format }) }
373
373
  if (!(buffer instanceof Buffer)) { throw Object.assign(new Error("buffer must be a Buffer"), { buffer }) }
374
374
  if (buffer.length < stride * height) { throw Object.assign(new Error("buffer is smaller than expected"), { buffer, stride, height }) }
375
+ if (scaling !== undefined && typeof scaling !== 'string') { throw Object.assign(new Error("scaling must be a string"), { scaling }) }
375
376
 
376
377
  const _format = Enums.pixelFormat[format]
377
378
  if (_format === undefined) { throw Object.assign(new Error("invalid format"), { format }) }
378
379
 
379
- Bindings.window_render(this._id, width, height, stride, _format, buffer)
380
+ const _scaling = Enums.scaleMode[scaling]
381
+ if (_scaling === undefined) { throw Object.assign(new Error("invalid scaling"), { scaling }) }
382
+
383
+ Bindings.window_render(this._id, width, height, stride, _format, buffer, _scaling)
380
384
  }
381
385
 
382
386
  setIcon (width, height, stride, format, buffer) {
@@ -44,6 +44,11 @@ enums::get(const Napi::CallbackInfo &info)
44
44
  pixel_formats.Set("nv12", Napi::Number::New(env, SDL_PIXELFORMAT_NV12));
45
45
  pixel_formats.Set("nv21", Napi::Number::New(env, SDL_PIXELFORMAT_NV21));
46
46
 
47
+ Napi::Object scale_mode = Napi::Object::New(env);
48
+ scale_mode.Set("nearest", Napi::Number::New(env, SDL_ScaleModeNearest));
49
+ scale_mode.Set("linear", Napi::Number::New(env, SDL_ScaleModeLinear));
50
+ scale_mode.Set("best", Napi::Number::New(env, SDL_ScaleModeBest));
51
+
47
52
  Napi::Object audio_formats = Napi::Object::New(env);
48
53
  audio_formats.Set("s8", Napi::Number::New(env, AUDIO_S8));
49
54
  audio_formats.Set("u8", Napi::Number::New(env, AUDIO_U8));
@@ -330,6 +335,7 @@ enums::get(const Napi::CallbackInfo &info)
330
335
 
331
336
  Napi::Object all = Napi::Object::New(env);
332
337
  all.Set("pixelFormat", pixel_formats);
338
+ all.Set("scaleMode", scale_mode);
333
339
  all.Set("audioFormat", audio_formats);
334
340
  all.Set("scancodes", scancodes);
335
341
  all.Set("mouseButtons", mouse_buttons);
@@ -529,6 +529,7 @@ window::render (const Napi::CallbackInfo &info)
529
529
  int stride = info[3].As<Napi::Number>().Int32Value();
530
530
  unsigned int format = info[4].As<Napi::Number>().Int32Value();
531
531
  void *pixels = info[5].As<Napi::Buffer<char>>().Data();
532
+ SDL_ScaleMode scaling = static_cast<SDL_ScaleMode>(info[6].As<Napi::Number>().Int32Value());
532
533
 
533
534
  SDL_Window *window = SDL_GetWindowFromID(window_id);
534
535
  if (window == nullptr) {
@@ -571,6 +572,13 @@ window::render (const Napi::CallbackInfo &info)
571
572
  throw Napi::Error::New(env, message.str());
572
573
  }
573
574
 
575
+ if(SDL_SetTextureScaleMode(texture, scaling) < 0) {
576
+ std::ostringstream message;
577
+ message << "SDL_SetTextureScaleMode(" << window_id << ", " << scaling << ") error: " << SDL_GetError();
578
+ SDL_ClearError();
579
+ throw Napi::Error::New(env, message.str());
580
+ }
581
+
574
582
  if (SDL_RenderClear(renderer) < 0) {
575
583
  SDL_DestroyTexture(texture);
576
584
  SDL_FreeSurface(surface);
@@ -351,6 +351,11 @@ export namespace Sdl {
351
351
  | 'nv12'
352
352
  | 'nv21'
353
353
 
354
+ export type Scaling
355
+ = 'nearest'
356
+ | 'linear'
357
+ | 'best'
358
+
354
359
  export interface Display {
355
360
  readonly name: string
356
361
  readonly format: Format
@@ -417,6 +422,7 @@ export namespace Sdl {
417
422
 
418
423
  readonly pixelWidth: number
419
424
  readonly pixelHeight: number
425
+ setSizeInPixels (pixelWidth: number, pixelHeight: number): void
420
426
 
421
427
  readonly visible: boolean
422
428
  show (show?: boolean): void
@@ -461,7 +467,7 @@ export namespace Sdl {
461
467
  readonly tooltip: boolean
462
468
  readonly utility: boolean
463
469
 
464
- render (width: number, height: number, stride: number, format: Format, buffer: Buffer): void
470
+ render (width: number, height: number, stride: number, format: Format, buffer: Buffer, scaling?: Scaling): void
465
471
 
466
472
  setIcon (width: number, height: number, stride: number, format: Format, buffer: Buffer): void
467
473
 
@@ -470,6 +476,7 @@ export namespace Sdl {
470
476
 
471
477
  readonly destroyed: boolean
472
478
  destroy (): void
479
+ destroyGently (): void
473
480
  }
474
481
 
475
482
  interface Module {