@kmamal/sdl 0.11.8 → 0.11.9
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 +11 -1
- package/README.md +256 -226
- package/package.json +11 -9
- package/scripts/util/common.js +1 -1
- package/src/javascript/controller/device.js +1 -1
- package/src/javascript/controller/index.js +2 -2
- package/src/javascript/events/reconcile-audio-devices.js +2 -1
- package/src/javascript/events/reconcile-displays.js +2 -1
- package/src/javascript/events/reconcile-joystick-and-controller-devices.js +5 -2
- package/src/native/controller.cpp +1 -1
- package/src/native/global.cpp +6 -2
- package/src/native/joystick.cpp +31 -40
- package/src/native/joystick.h +1 -0
- package/src/native/sensor.cpp +0 -1
- package/src/native/video.cpp +6 -8
- package/src/types/index.d.ts +9 -9
package/README.md
CHANGED
|
@@ -4,32 +4,41 @@
|
|
|
4
4
|
[](https://libraries.io/npm/@kmamal%2Fsdl)
|
|
5
5
|
[](https://opensource.org/licenses/MIT)
|
|
6
6
|
|
|
7
|
-
SDL bindings for Node.js.
|
|
8
|
-
Provides window management, input events (keyboard, mouse, joysticks, controllers, sensors), audio playback and recording, clipboard manipulation, and battery status.
|
|
7
|
+
SDL bindings for Node.js. Provides access to systems that are not normally available to Node.js applications:
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
- 💻 Window management
|
|
10
|
+
- ⌨ Keyboard
|
|
11
|
+
- 🖱 Mouse
|
|
12
|
+
- 🕹 Joysticks
|
|
13
|
+
- 🎮 Controllers
|
|
14
|
+
- 🔈 Audio playback
|
|
15
|
+
- 🎤 Audio recording
|
|
16
|
+
- 📋 Clipboard manipulation
|
|
17
|
+
- 🔋 Battery status
|
|
18
|
+
- 🧭 Sensors
|
|
12
19
|
|
|
13
|
-
|
|
20
|
+
Also allows using Canvas2D, WebGL, and WebGPU without a browser:
|
|
14
21
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
22
|
+
* __Canvas2D:__ Available via [@napi-rs/canvas](https://www.npmjs.com/package/@napi-rs/canvas). In my experience, this is the fastest library out of the many available on npm.
|
|
23
|
+
* __WebGL:__ Available via [@kmamal/gl](https://github.com/kmamal/headless-gl#readme). This is a fork of [headless-gl](https://github.com/stackgl/headless-gl#readme) that I've modified to render directly on SDL windows.
|
|
24
|
+
* __WebGPU:__ Available via [@kmamal/gpu](https://github.com/kmamal/gpu#readme). This is a fork of [Google Dawn](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/dawn/node/) that I've modified to render directly on SDL windows.
|
|
25
|
+
|
|
26
|
+
Officially supports Linux (x64, arm64), Mac (x64, arm64), and Windows (x64).
|
|
27
|
+
Should technically work for any system supported by both SDL and Node.js, but I haven't tried.
|
|
28
|
+
Prebuilt binaries are available for the supported architectures.
|
|
20
29
|
|
|
21
30
|
|
|
22
31
|
## Installation
|
|
23
32
|
|
|
24
|
-
|
|
25
|
-
This package is self-contained.
|
|
26
|
-
Just run:
|
|
33
|
+
This package is self-contained. Just run:
|
|
27
34
|
|
|
28
35
|
```bash
|
|
29
36
|
npm install @kmamal/sdl
|
|
30
37
|
```
|
|
31
38
|
|
|
32
|
-
|
|
39
|
+
You do __not__ have to manually install any other libs or DLLs to your system. A compatible version of SDL will be automatically downloaded by the install script and placed inside `node_modules` along with this lib's prebuilt binding binaries.
|
|
40
|
+
|
|
41
|
+
(But if the install script fails, have a look at the instructions for [building the package manually](#building-from-source))
|
|
33
42
|
|
|
34
43
|
|
|
35
44
|
## Examples
|
|
@@ -362,9 +371,9 @@ Check the [`examples/`](https://github.com/kmamal/node-sdl/tree/master/examples#
|
|
|
362
371
|
|
|
363
372
|
* `<object>`
|
|
364
373
|
* `version: <object>`
|
|
365
|
-
* `compile: <object>` The
|
|
374
|
+
* `compile: <object>` The version of the SDL library that this package was compiled against.
|
|
366
375
|
* `major, minor, patch: <Semver>` The components of the version.
|
|
367
|
-
* `runtime: <object>` The
|
|
376
|
+
* `runtime: <object>` The version of the SDL library that was found and loaded at runtime.
|
|
368
377
|
* `major, minor, patch: <Semver>` The components of the version.
|
|
369
378
|
* `platform: <string>` The name of the platform we are running on. Possible values are: `'Linux'`, `'Windows'`, and `'Mac OS X'`.
|
|
370
379
|
* `drivers: <object>`
|
|
@@ -375,12 +384,13 @@ Check the [`examples/`](https://github.com/kmamal/node-sdl/tree/master/examples#
|
|
|
375
384
|
* `all: <string>[]` A list of all audio drivers.
|
|
376
385
|
* `current: <string>|<null>` The audio driver that is currently selected.
|
|
377
386
|
|
|
378
|
-
|
|
379
|
-
All the values
|
|
380
|
-
|
|
387
|
+
The `sdl.info` object is filled with information produced during the initialization of SDL.
|
|
388
|
+
All the values remain constant throughout the execution of the program.
|
|
389
|
+
|
|
390
|
+
To initialize SDL with video/audio drivers other than the default ones, set the appropriate [environment variables](https://wiki.libsdl.org/FAQUsingSDL) to the desired value.
|
|
381
391
|
|
|
382
|
-
Note that the `current` video or audio driver
|
|
383
|
-
This
|
|
392
|
+
Note that the `current` video or audio driver may be `null`.
|
|
393
|
+
This usually happens on systems that don't have any compatible devices, such as on a CI pipeline.
|
|
384
394
|
|
|
385
395
|
Sample data for Ubuntu:
|
|
386
396
|
|
|
@@ -409,7 +419,7 @@ Sample data for Ubuntu:
|
|
|
409
419
|
|
|
410
420
|
### Image data
|
|
411
421
|
|
|
412
|
-
There are 3 places in the API where you
|
|
422
|
+
There are 3 places in the API where you must provide an image to the library:
|
|
413
423
|
|
|
414
424
|
* [`window.render()`](#windowrenderwidth-height-stride-format-buffer-options)
|
|
415
425
|
* [`window.setIcon()`](#windowseticonwidth-height-stride-format-buffer)
|
|
@@ -419,11 +429,11 @@ All three of these functions accept the image as a series of arguments:
|
|
|
419
429
|
|
|
420
430
|
* `width: <number>` The width of the image in pixels.
|
|
421
431
|
* `height: <number>` The height of the image in pixels.
|
|
422
|
-
* `stride: <number>` How many bytes each row of the image takes up in the buffer.
|
|
432
|
+
* `stride: <number>` How many bytes each row of the image takes up in the buffer. Usually equal to `width * bytesPerPixel`, but may be larger if the rows of the buffer are padded to always be some multiple of bytes.
|
|
423
433
|
* `format: `[`<PixelFormat>`](#pixel-formats) The binary representation of the data in the buffer.
|
|
424
434
|
* `buffer: <Buffer>` Holds the actual pixel data for the image, in the format and layout specified by all the above arguments.
|
|
425
435
|
|
|
426
|
-
So for example, to fill the window with a red+green gradient you could do:
|
|
436
|
+
So, for example, to fill the window with a red+green gradient you could do:
|
|
427
437
|
|
|
428
438
|
```js
|
|
429
439
|
const { pixelWidth: width, pixelHeight: height } = window
|
|
@@ -445,11 +455,12 @@ window.render(width, height, stride, 'rgba32', buffer)
|
|
|
445
455
|
|
|
446
456
|
### High-DPI
|
|
447
457
|
|
|
448
|
-
On a high-dpi display, windows have more pixels
|
|
449
|
-
On such systems `width` and `height` (and all other measurements such as `x` and `y`) are in "points".
|
|
450
|
-
Points are abstract and don't
|
|
451
|
-
If you need to
|
|
452
|
-
You
|
|
458
|
+
On a high-dpi display, windows have more pixels than their `width` and `height` would indicate.
|
|
459
|
+
On such systems `width` and `height` (and all other measurements such as `x` and `y`) are measured in "points" instead of pixels.
|
|
460
|
+
Points are an abstract unit of measurement and don't necessarily correspond to pixels.
|
|
461
|
+
If you need to work with pixels, you can use the window's `pixelWidth` and `pixelHeight` properties.
|
|
462
|
+
You usually need these values when creating a "surface" that will be displayed on the window, such as a Buffer, Canvas, or 3D rendering viewport.
|
|
463
|
+
I recommend that in these cases you always use `pixelWidth` and `pixelHeight`, since you don't know beforehand if your program will be running on a high-dpi system or not.
|
|
453
464
|
|
|
454
465
|
### Pixel formats
|
|
455
466
|
|
|
@@ -526,7 +537,7 @@ Fired when a display changes position.
|
|
|
526
537
|
### sdl.video.displays
|
|
527
538
|
|
|
528
539
|
* `<object>[]`
|
|
529
|
-
* `name: <string>` The name of the display.
|
|
540
|
+
* `name: <string>|<null>` The name of the display, or `null` if it can't be determined.
|
|
530
541
|
* `format: `[`<PixelFormat>`](#pixel-formats) The pixel format of the display.
|
|
531
542
|
* `frequency: <number>` The refresh rate of the display.
|
|
532
543
|
* `geometry: <object>` The desktop region represented by the display.
|
|
@@ -561,7 +572,7 @@ Notice how the geometries don't overlap:
|
|
|
561
572
|
frequency: 60,
|
|
562
573
|
geometry: { x: 0, y: 0, width: 1920, height: 1080 },
|
|
563
574
|
usable: { x: 0, y: 27, width: 1920, height: 1053 },
|
|
564
|
-
dpi: { horizontal: 141.76, vertical: 142.13, diagonal: 141.85 }
|
|
575
|
+
dpi: { horizontal: 141.76, vertical: 142.13, diagonal: 141.85 },
|
|
565
576
|
},
|
|
566
577
|
{
|
|
567
578
|
name: '1',
|
|
@@ -569,7 +580,7 @@ Notice how the geometries don't overlap:
|
|
|
569
580
|
frequency: 60,
|
|
570
581
|
geometry: { x: 1920, y: 0, width: 1920, height: 1080 },
|
|
571
582
|
usable: { x: 1920, y: 27, width: 1920, height: 1053 },
|
|
572
|
-
dpi: { horizontal: 141.76, vertical: 142.13, diagonal: 141.85 }
|
|
583
|
+
dpi: { horizontal: 141.76, vertical: 142.13, diagonal: 141.85 },
|
|
573
584
|
},
|
|
574
585
|
]
|
|
575
586
|
```
|
|
@@ -595,68 +606,68 @@ The window that the mouse is hovered over, or `null` if the mouse is not over a
|
|
|
595
606
|
### sdl.video.createWindow([options])
|
|
596
607
|
|
|
597
608
|
* `options: <object>`
|
|
598
|
-
* `title: <string>`
|
|
599
|
-
* `display: <number>` An object from `sdl.video.displays` to specify in which display the window
|
|
600
|
-
* `x: <number>` The x position in which the window
|
|
601
|
-
* `y: <number>` The y position in which the window
|
|
609
|
+
* `title: <string>` Appears in the window's title bar. Default: `''`
|
|
610
|
+
* `display: <number>` An object from `sdl.video.displays` to specify in which display the window should appear (if you have multiple displays). Default: `sdl.video.displays[0]`
|
|
611
|
+
* `x: <number>` The x position in which the window should appear relative to the screen, or `null` for centered. Default: `null`
|
|
612
|
+
* `y: <number>` The y position in which the window should appear relative to the screen, or `null` for centered. Default: `null`
|
|
602
613
|
* `width: <number>` The width of the window. Default: `640`
|
|
603
614
|
* `height: <number>` The height of the window. Default: `480`
|
|
604
615
|
* `visible: <boolean>` Set to `false` to create a hidden window that will only be shown when you call [`window.show()`](#windowshowshow). Default: `true`
|
|
605
616
|
* `fullscreen: <boolean>` Set to `true` to create the window in fullscreen mode. Default: `false`
|
|
606
617
|
* `resizable: <boolean>` Set to `true` to allow resizing the window by dragging its borders. Default: `false`
|
|
607
618
|
* `borderless: <boolean>` Set to `true` to completely hide the window's borders and title bar. Default: `false`
|
|
608
|
-
* `alwaysOnTop: <boolean>` Set to `true` to always show
|
|
619
|
+
* `alwaysOnTop: <boolean>` Set to `true` to always show the window above others. Default: `false`
|
|
609
620
|
* `accelerated: <boolean>` Set to `false` to disable hardware accelerated rendering. Default: `true`
|
|
610
621
|
* `vsync: <boolean>` Set to `false` to disable frame rate synchronization. Default: `true`
|
|
611
622
|
* `opengl: <boolean>` Set to `true` to create an OpenGL-compatible window (for use with [@kmamal/gl](https://github.com/kmamal/headless-gl#readme)). Default: `false`
|
|
612
623
|
* `webgpu: <boolean>` Set to `true` to create an WebGPU-compatible window (for use with [@kmamal/gpu](https://github.com/kmamal/gpu#readme)). Default: `false`
|
|
613
|
-
* `skipTaskbar: <boolean>` X11 only. Set to `true` to not add
|
|
614
|
-
* `popupMenu: <boolean>` X11 only. Set to `true` to treat
|
|
615
|
-
* `tooltip: <boolean>` X11 only. Set to `true` to treat
|
|
616
|
-
* `utility: <boolean>` X11 only. Set to `true` to treat
|
|
624
|
+
* `skipTaskbar: <boolean>` X11 only. Set to `true` to not add the window to the taskbar. Default: `false`
|
|
625
|
+
* `popupMenu: <boolean>` X11 only. Set to `true` to treat the window like a popup menu. Default: `false`
|
|
626
|
+
* `tooltip: <boolean>` X11 only. Set to `true` to treat the window like a tooltip. Default: `false`
|
|
627
|
+
* `utility: <boolean>` X11 only. Set to `true` to treat the window like a utility window. Default: `false`
|
|
617
628
|
* Returns: [`<Window>`](#class-window) an object representing the new window.
|
|
618
629
|
|
|
619
630
|
Creates a new window.
|
|
620
631
|
|
|
621
632
|
The following restrictions apply:
|
|
622
633
|
|
|
623
|
-
*
|
|
634
|
+
* The `display` option is mutually exclusive with the `x` and `y` options.
|
|
624
635
|
* The `resizable` and `borderless` options are mutually exclusive.
|
|
625
636
|
* The `opengl` and `webgpu` options are mutually exclusive.
|
|
626
637
|
* The `vsync` option only applies to windows that are also `accelerated`.
|
|
627
638
|
* The `accelerated` and `vsync` options have no effect if either `opengl` or `webgpu` is also specified.
|
|
628
639
|
|
|
629
|
-
If you set the `opengl` or `webgpu` options, then you
|
|
640
|
+
If you set the `opengl` or `webgpu` options, then you must use OpenGL/WebGPU calls to render to the window.
|
|
630
641
|
Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-options) will fail.
|
|
631
642
|
|
|
632
643
|
## class Window
|
|
633
644
|
|
|
634
|
-
|
|
635
|
-
Instead, objects returned by [`sdl.video.createWindow()`](#sdlvideocreatewindowoptions) are of
|
|
645
|
+
The `Window` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
646
|
+
Instead, objects returned by [`sdl.video.createWindow()`](#sdlvideocreatewindowoptions) are of type `Window`.
|
|
636
647
|
|
|
637
648
|
### Event: 'show'
|
|
638
649
|
|
|
639
|
-
Fired when
|
|
650
|
+
Fired when the window becomes visible.
|
|
640
651
|
|
|
641
652
|
### Event: 'hide'
|
|
642
653
|
|
|
643
|
-
Fired when
|
|
654
|
+
Fired when the window becomes hidden.
|
|
644
655
|
|
|
645
656
|
### Event: 'expose'
|
|
646
657
|
|
|
647
|
-
Fired when
|
|
658
|
+
Fired when the window becomes exposed and should be redrawn.
|
|
648
659
|
|
|
649
660
|
### Event: 'minimize'
|
|
650
661
|
|
|
651
|
-
Fired when
|
|
662
|
+
Fired when the window becomes minimized.
|
|
652
663
|
|
|
653
664
|
### Event: 'maximize'
|
|
654
665
|
|
|
655
|
-
Fired when
|
|
666
|
+
Fired when the window becomes maximized.
|
|
656
667
|
|
|
657
668
|
### Event: 'restore'
|
|
658
669
|
|
|
659
|
-
Fired when
|
|
670
|
+
Fired when the window gets restored.
|
|
660
671
|
|
|
661
672
|
### Event: 'move'
|
|
662
673
|
|
|
@@ -678,15 +689,15 @@ Fired when the window changes size.
|
|
|
678
689
|
|
|
679
690
|
* `display: <object>` An object from [`sdl.video.displays`](#sdlvideodisplays) indicating the window's new display.
|
|
680
691
|
|
|
681
|
-
Fired when
|
|
692
|
+
Fired when the window moves from one display to another.
|
|
682
693
|
|
|
683
694
|
### Event: 'focus'
|
|
684
695
|
|
|
685
|
-
Fired when
|
|
696
|
+
Fired when the window gains the keyboard focus.
|
|
686
697
|
|
|
687
698
|
### Event: 'blur'
|
|
688
699
|
|
|
689
|
-
Fired when
|
|
700
|
+
Fired when the window loses the keyboard focus.
|
|
690
701
|
|
|
691
702
|
### Event: 'hover'
|
|
692
703
|
|
|
@@ -698,11 +709,11 @@ Fired when the mouse leaves the window.
|
|
|
698
709
|
|
|
699
710
|
### Event: 'beforeClose'
|
|
700
711
|
|
|
701
|
-
* `prevent: <function (void) => void>` Call this to prevent the window from closing.
|
|
712
|
+
* `prevent: <function (void) => void>` Call this function to prevent the window from closing.
|
|
702
713
|
|
|
703
|
-
Fired to indicate that the user
|
|
704
|
-
If you need to display any confirmation dialogs
|
|
705
|
-
If `prevent` is not called, then
|
|
714
|
+
Fired to indicate that the user requested that the window should close (usually by clicking the "x" button).
|
|
715
|
+
If you need to display any confirmation dialogs, call `event.prevent()` and afterwards handle destruction manually.
|
|
716
|
+
If `prevent` is not called, then the `beforeClose` event will be followed by a [`'close'`](#event-close) event.
|
|
706
717
|
|
|
707
718
|
### Event: 'close'
|
|
708
719
|
|
|
@@ -742,13 +753,13 @@ Fired when a key is released.
|
|
|
742
753
|
|
|
743
754
|
* `text: <string>` The unicode representation of the character that was entered.
|
|
744
755
|
|
|
745
|
-
Fired when
|
|
756
|
+
Fired when text is entered via the keyboard.
|
|
746
757
|
|
|
747
758
|
### Event: 'mouseButtonDown'
|
|
748
759
|
|
|
749
760
|
* `x: <number>` The mouse's x position when the event happened, relative to the window.
|
|
750
761
|
* `y: <number>` The mouse's y position when the event happened, relative to the window.
|
|
751
|
-
* `touch: <boolean>`
|
|
762
|
+
* `touch: <boolean>` Is `true` if the event was caused by a touch event.
|
|
752
763
|
* `button: `[`<sdl.mouse.BUTTON>`](#enum-button) The button that was pressed.
|
|
753
764
|
|
|
754
765
|
Fired when a mouse button is pressed.
|
|
@@ -757,7 +768,7 @@ Fired when a mouse button is pressed.
|
|
|
757
768
|
|
|
758
769
|
* `x: <number>` The mouse's x position when the event happened, relative to the window.
|
|
759
770
|
* `y: <number>` The mouse's y position when the event happened, relative to the window.
|
|
760
|
-
* `touch: <boolean>`
|
|
771
|
+
* `touch: <boolean>` Is `true` if the event was caused by a touch event.
|
|
761
772
|
* `button: `[`<sdl.mouse.BUTTON>`](#enum-button) The button that was released.
|
|
762
773
|
|
|
763
774
|
Fired when a mouse button is released.
|
|
@@ -766,7 +777,7 @@ Fired when a mouse button is released.
|
|
|
766
777
|
|
|
767
778
|
* `x: <number>` The mouse's x position when the event happened, relative to the window.
|
|
768
779
|
* `y: <number>` The mouse's y position when the event happened, relative to the window.
|
|
769
|
-
* `touch: <boolean>`
|
|
780
|
+
* `touch: <boolean>` Is `true` if the event was caused by a touch event.
|
|
770
781
|
|
|
771
782
|
Fired when the mouse moves.
|
|
772
783
|
|
|
@@ -774,16 +785,16 @@ Fired when the mouse moves.
|
|
|
774
785
|
|
|
775
786
|
* `x: <number>` The mouse's x position when the event happened, relative to the window.
|
|
776
787
|
* `y: <number>` The mouse's y position when the event happened, relative to the window.
|
|
777
|
-
* `touch: <boolean>`
|
|
788
|
+
* `touch: <boolean>` Is `true` if the event was caused by a touch event.
|
|
778
789
|
* `dx: <number>` The wheel's x movement, relative to its last position.
|
|
779
790
|
* `dy: <number>` The wheel's y movement, relative to its last position.
|
|
780
|
-
* `flipped: <boolean>`
|
|
791
|
+
* `flipped: <boolean>` Is `true` if the underlying platform reverses the mouse wheel's scroll direction. Multiply `dx` and `dy` by `-1` to get the correct values.
|
|
781
792
|
|
|
782
793
|
Fired when the mouse wheel is scrolled.
|
|
783
794
|
|
|
784
795
|
### Event: 'dropBegin'
|
|
785
796
|
|
|
786
|
-
When
|
|
797
|
+
When you drop a set of items onto a window, first the [`'dropBegin'`](#event-dropbegin) event is fired, then a number of [`'dropText'`](#event-droptext) and/or [`'dropFile'`](#event-dropfile) events are fired, corresponding to the contents of the drop, then finally the [`'dropComplete'`](#event-dropcomplete) event is fired.
|
|
787
798
|
|
|
788
799
|
### Event: 'dropText'
|
|
789
800
|
|
|
@@ -854,13 +865,15 @@ The window's height.
|
|
|
854
865
|
|
|
855
866
|
* `<number>`
|
|
856
867
|
|
|
857
|
-
The window's width in pixels.
|
|
868
|
+
The window's width in pixels.
|
|
869
|
+
Is larger than [`width`](#windowwidth) on [high-dpi](#high-dpi) displays.
|
|
858
870
|
|
|
859
871
|
### window.pixelHeight
|
|
860
872
|
|
|
861
873
|
* `<number>`
|
|
862
874
|
|
|
863
|
-
The window's height in pixels.
|
|
875
|
+
The window's height in pixels.
|
|
876
|
+
Is larger than [`height`](#windowheight) on [high-dpi](#high-dpi) displays.
|
|
864
877
|
|
|
865
878
|
### window.setSize(width, height)
|
|
866
879
|
|
|
@@ -881,14 +894,14 @@ This function only behaves differently from [`window.setSize()`](#windowsetsizew
|
|
|
881
894
|
|
|
882
895
|
* `<object>`
|
|
883
896
|
|
|
884
|
-
An object from [`sdl.video.displays`](#sdlvideodisplays) indicating the display
|
|
885
|
-
If the window spans multiple displays, then the display
|
|
897
|
+
An object from [`sdl.video.displays`](#sdlvideodisplays) indicating the display the window belongs to.
|
|
898
|
+
If the window spans multiple displays, then the display that contains the center of the window is returned.
|
|
886
899
|
|
|
887
900
|
### window.visible
|
|
888
901
|
|
|
889
902
|
* `<boolean>`
|
|
890
903
|
|
|
891
|
-
|
|
904
|
+
Is `true` if the window is visible.
|
|
892
905
|
|
|
893
906
|
### window.show([show])
|
|
894
907
|
|
|
@@ -904,7 +917,7 @@ Equivalent to [`window.show(false)`](#windowshowshow).
|
|
|
904
917
|
|
|
905
918
|
* `<boolean>`
|
|
906
919
|
|
|
907
|
-
|
|
920
|
+
Is `true` if the window is fullscreen.
|
|
908
921
|
A fullscreen window is displayed over the entire screen.
|
|
909
922
|
|
|
910
923
|
### window.setFullscreen(fullscreen)
|
|
@@ -917,8 +930,8 @@ Changes the window's fullscreen property.
|
|
|
917
930
|
|
|
918
931
|
* `<boolean>`
|
|
919
932
|
|
|
920
|
-
|
|
921
|
-
A resizable window can be resized by dragging
|
|
933
|
+
Is `true` if the window is resizable.
|
|
934
|
+
A resizable window can be resized by dragging its borders.
|
|
922
935
|
|
|
923
936
|
### window.setResizable(resizable)
|
|
924
937
|
|
|
@@ -930,7 +943,7 @@ Changes the window's resizable property.
|
|
|
930
943
|
|
|
931
944
|
* `<boolean>`
|
|
932
945
|
|
|
933
|
-
|
|
946
|
+
Is `true` if the window is borderless.
|
|
934
947
|
A borderless window has no borders or title bar.
|
|
935
948
|
|
|
936
949
|
### window.setBorderless(borderless)
|
|
@@ -943,14 +956,14 @@ Changes the window's borderless property.
|
|
|
943
956
|
|
|
944
957
|
* `<boolean>`
|
|
945
958
|
|
|
946
|
-
|
|
947
|
-
Such a window
|
|
959
|
+
Is `true` if the window was created with `alwaysOnTop: true`.
|
|
960
|
+
Such a window is always be shown above other windows.
|
|
948
961
|
|
|
949
962
|
### window.accelerated
|
|
950
963
|
|
|
951
964
|
* `<boolean>`
|
|
952
965
|
|
|
953
|
-
|
|
966
|
+
Is `true` if the window is using hardware accelerated rendering.
|
|
954
967
|
|
|
955
968
|
### window.setAccelerated(accelerated)
|
|
956
969
|
|
|
@@ -964,9 +977,9 @@ If you have set the `opengl` or `webgpu` options, then calls to this function wi
|
|
|
964
977
|
|
|
965
978
|
* `<boolean>`
|
|
966
979
|
|
|
967
|
-
|
|
968
|
-
|
|
969
|
-
Note that vsync can only be
|
|
980
|
+
Is `true` if the window is using vsync.
|
|
981
|
+
Vsync synchronizes the window's frame rate with the display's refresh rate to prevent tearing.
|
|
982
|
+
Note that vsync can only be set to `true` if [`accelerated`](#windowaccelerated) is also `true`.
|
|
970
983
|
|
|
971
984
|
### window.setVsync(vsync)
|
|
972
985
|
|
|
@@ -980,16 +993,16 @@ If you have set the `opengl` or `webgpu` options, then calls to this function wi
|
|
|
980
993
|
|
|
981
994
|
* `<boolean>`
|
|
982
995
|
|
|
983
|
-
|
|
984
|
-
In OpenGL mode, you
|
|
996
|
+
Is `true` if the window was created in OpenGl mode.
|
|
997
|
+
In OpenGL mode, you must use OpenGL calls to render to the window.
|
|
985
998
|
Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-options) will fail.
|
|
986
999
|
|
|
987
1000
|
### window.webgpu
|
|
988
1001
|
|
|
989
1002
|
* `<boolean>`
|
|
990
1003
|
|
|
991
|
-
|
|
992
|
-
In WebGPU mode, you
|
|
1004
|
+
Is `true` if the window was created in WebGPU mode.
|
|
1005
|
+
In WebGPU mode, you must use WebGPU calls to render to the window.
|
|
993
1006
|
Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-options) will fail.
|
|
994
1007
|
|
|
995
1008
|
### window.native
|
|
@@ -1000,14 +1013,15 @@ Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-options) wi
|
|
|
1000
1013
|
The native type of `handle` is HWND on Windows, NSView* on macOS, and Window (unsigned long) on Linux.
|
|
1001
1014
|
It should work exactly like the [`win.getNativeWindowHandle()`](https://www.electronjs.org/docs/latest/api/browser-window#wingetnativewindowhandle) electron method.
|
|
1002
1015
|
|
|
1003
|
-
|
|
1004
|
-
Please ignore these.
|
|
1016
|
+
The `window.native` object might also sometimes include extra fields other than the ones documented here.
|
|
1017
|
+
Please ignore and do not use these.
|
|
1018
|
+
They are used internally for passing to [@kmamal/gl](https://github.com/kmamal/headless-gl#readme) or [@kmamal/gpu](https://github.com/kmamal/gpu#readme) and can change at any time.
|
|
1005
1019
|
|
|
1006
1020
|
### window.maximized
|
|
1007
1021
|
|
|
1008
1022
|
* `<boolean>`
|
|
1009
1023
|
|
|
1010
|
-
|
|
1024
|
+
Is `true` if the window is maximized.
|
|
1011
1025
|
|
|
1012
1026
|
### window.maximize()
|
|
1013
1027
|
|
|
@@ -1017,7 +1031,7 @@ Maximizes the window.
|
|
|
1017
1031
|
|
|
1018
1032
|
* `<boolean>`
|
|
1019
1033
|
|
|
1020
|
-
|
|
1034
|
+
Is `true` if the window is minimized.
|
|
1021
1035
|
|
|
1022
1036
|
### window.minimize()
|
|
1023
1037
|
|
|
@@ -1025,13 +1039,13 @@ Minimizes the window.
|
|
|
1025
1039
|
|
|
1026
1040
|
### window.restore()
|
|
1027
1041
|
|
|
1028
|
-
Restores the window so it
|
|
1042
|
+
Restores the window so it is neither minimized nor maximized.
|
|
1029
1043
|
|
|
1030
1044
|
### window.focused
|
|
1031
1045
|
|
|
1032
1046
|
* `<boolean>`
|
|
1033
1047
|
|
|
1034
|
-
|
|
1048
|
+
Is `true` if the window has keyboard input.
|
|
1035
1049
|
|
|
1036
1050
|
### window.focus()
|
|
1037
1051
|
|
|
@@ -1041,39 +1055,39 @@ Gives the window the keyboard focus.
|
|
|
1041
1055
|
|
|
1042
1056
|
* `<boolean>`
|
|
1043
1057
|
|
|
1044
|
-
|
|
1058
|
+
Is `true` if the mouse is over the window.
|
|
1045
1059
|
|
|
1046
1060
|
### window.skipTaskbar
|
|
1047
1061
|
|
|
1048
1062
|
* `<boolean>`
|
|
1049
1063
|
|
|
1050
1064
|
X11 only.
|
|
1051
|
-
|
|
1052
|
-
Such a window
|
|
1065
|
+
Is `true` if the window was created with `skipTaskbar: true`.
|
|
1066
|
+
Such a window is not added to the taskbar.
|
|
1053
1067
|
|
|
1054
1068
|
### window.popupMenu
|
|
1055
1069
|
|
|
1056
1070
|
* `<boolean>`
|
|
1057
1071
|
|
|
1058
1072
|
X11 only.
|
|
1059
|
-
|
|
1060
|
-
Such a window
|
|
1073
|
+
Is `true` if the window was created with `popupMenu: true`.
|
|
1074
|
+
Such a window is always treated as a popup menu.
|
|
1061
1075
|
|
|
1062
1076
|
### window.tooltip
|
|
1063
1077
|
|
|
1064
1078
|
* `<boolean>`
|
|
1065
1079
|
|
|
1066
1080
|
X11 only.
|
|
1067
|
-
|
|
1068
|
-
Such a window
|
|
1081
|
+
Is `true` if the window was created with `tooltip: true`.
|
|
1082
|
+
Such a window is always treated as a tooltip.
|
|
1069
1083
|
|
|
1070
1084
|
### window.utility
|
|
1071
1085
|
|
|
1072
1086
|
* `<boolean>`
|
|
1073
1087
|
|
|
1074
1088
|
X11 only.
|
|
1075
|
-
|
|
1076
|
-
Such a window
|
|
1089
|
+
Is `true` if the window was created with `utility: true`.
|
|
1090
|
+
Such a window is always treated as a utility window.
|
|
1077
1091
|
|
|
1078
1092
|
### window.render(width, height, stride, format, buffer[, options])
|
|
1079
1093
|
|
|
@@ -1086,7 +1100,7 @@ Such a window will always be treated as a utility window.
|
|
|
1086
1100
|
Displays an image in the window.
|
|
1087
1101
|
|
|
1088
1102
|
By default the image is displayed over the entire surface of the window.
|
|
1089
|
-
You
|
|
1103
|
+
You may pass the optional `dstRect` parameter to set where exactly on the window to display the image.
|
|
1090
1104
|
The rest of the window will be filled with black.
|
|
1091
1105
|
|
|
1092
1106
|
If the dimensions of the image do not match the dimensions of the area it should be displayed in, then the image will be stretched to match.
|
|
@@ -1099,7 +1113,7 @@ Possible values are:
|
|
|
1099
1113
|
| `'linear'` | `SDL_ScaleModeLinear` | linear filtering |
|
|
1100
1114
|
| `'best'` | `SDL_ScaleModeBest` | anisotropic filtering |
|
|
1101
1115
|
|
|
1102
|
-
If the window was created with either of the `opengl` or `webgpu` options, then you
|
|
1116
|
+
If the window was created with either of the `opengl` or `webgpu` options, then you must use OpenGL/WebGPU calls to render to the window.
|
|
1103
1117
|
Calls to `render()` will fail.
|
|
1104
1118
|
|
|
1105
1119
|
### window.setIcon(width, height, stride, format, buffer)
|
|
@@ -1113,7 +1127,7 @@ Set's the window's icon, usually displayed in the title bar and the taskbar.
|
|
|
1113
1127
|
* `untilFocused: <boolean>` Whether to keep flashing the window until the user focuses it. Default: `false`
|
|
1114
1128
|
|
|
1115
1129
|
Flash the window briefly to get attention.
|
|
1116
|
-
If `untilFocused` is set, the window will
|
|
1130
|
+
If `untilFocused` is set, the window will continue flashing until the user focuses it.
|
|
1117
1131
|
|
|
1118
1132
|
### window.stopFlashing()
|
|
1119
1133
|
|
|
@@ -1123,8 +1137,8 @@ Stop the window from flashing.
|
|
|
1123
1137
|
|
|
1124
1138
|
* `<boolean>`
|
|
1125
1139
|
|
|
1126
|
-
|
|
1127
|
-
A destroyed window object
|
|
1140
|
+
Is `true` if the window is destroyed.
|
|
1141
|
+
A destroyed window object must not be used any further.
|
|
1128
1142
|
|
|
1129
1143
|
### window.destroy()
|
|
1130
1144
|
|
|
@@ -1133,7 +1147,7 @@ Destroys the window.
|
|
|
1133
1147
|
### window.destroyGently()
|
|
1134
1148
|
|
|
1135
1149
|
Asks before destroying the window.
|
|
1136
|
-
The difference between this function and [destroy()](#windowdestroy) is that this function
|
|
1150
|
+
The difference between this function and [destroy()](#windowdestroy) is that this function first makes the window emit the [`'beforeClose'`](#event-beforeclose) event, giving you a chance to prevent the window from being destroyed.
|
|
1137
1151
|
|
|
1138
1152
|
|
|
1139
1153
|
## sdl.keyboard
|
|
@@ -1146,7 +1160,8 @@ If your application cares about the layout of the keyboard (for example using th
|
|
|
1146
1160
|
|
|
1147
1161
|
For the most part it's better to treat scancode values as arbitrary/meaningless, but SDL does provide a scancode enumeration with values based on the [USB usage page standard](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf) so you should be able to derive some meaning from the scancodes if your keyboard is compatible.
|
|
1148
1162
|
|
|
1149
|
-
More commonly, you don't care about the physical key itself but about the "meaning" associated with each key:
|
|
1163
|
+
More commonly, you don't care about the physical key itself but about the "meaning" associated with each key:
|
|
1164
|
+
the character that it produces ("a", "b", "@", " ", .e.t.c.) or the function that it corresponds to ("Esc", "F4", "Ctrl", e.t.c.).
|
|
1150
1165
|
Your operating system provides a "keyboard mapping" that associates physical keys with their corresponding meaning.
|
|
1151
1166
|
Changing the keyboard mapping (for example by changing the language from English to German) will also change the corresponding meaning for each key (in the English-German example: the "y" and "z" keys will be switched).
|
|
1152
1167
|
These meanings are represented as [virtual key strings](#virtual-keys).
|
|
@@ -1443,14 +1458,14 @@ Retuns `null` if the scancode does not currespond to a key in the current mappin
|
|
|
1443
1458
|
|
|
1444
1459
|
Maps a key to the corresponding scancode based on the current keyboard mapping.
|
|
1445
1460
|
Retuns `null` if the key does not currespond to a scancode in the current mapping.
|
|
1446
|
-
If multiple physical keys produce the same virtual key, then only the first one
|
|
1461
|
+
If multiple physical keys produce the same virtual key, then only the first one is returned.
|
|
1447
1462
|
|
|
1448
1463
|
### sdl.keyboard.getState()
|
|
1449
1464
|
|
|
1450
|
-
* Returns: `<boolean[]>` an
|
|
1465
|
+
* Returns: `<boolean[]>` an array representing the state of each key.
|
|
1451
1466
|
|
|
1452
1467
|
The returned array can be indexed with [`Scancode`](#enum-scancode) values.
|
|
1453
|
-
|
|
1468
|
+
Each value in the array is either `true` if the corresponding key is pressed, or `false` otherwise.
|
|
1454
1469
|
|
|
1455
1470
|
|
|
1456
1471
|
## sdl.mouse
|
|
@@ -1469,7 +1484,7 @@ A mouse can have many buttons, but the values for the three most common ones are
|
|
|
1469
1484
|
### sdl.mouse.getButton(button)
|
|
1470
1485
|
|
|
1471
1486
|
* `button: <number>` The index of the button.
|
|
1472
|
-
* Returns: `<boolean>`
|
|
1487
|
+
* Returns: `<boolean>` Is `true` if the button is pressed.
|
|
1473
1488
|
|
|
1474
1489
|
Queries the state of a single mouse button.
|
|
1475
1490
|
|
|
@@ -1526,13 +1541,13 @@ The hotspot represents the pixel that is considered to be under the mouse.
|
|
|
1526
1541
|
|
|
1527
1542
|
### sdl.mouse.showCursor([show])
|
|
1528
1543
|
|
|
1529
|
-
* `show: <boolean>` If `true` then the mouse cursor
|
|
1544
|
+
* `show: <boolean>` If `true` then the mouse cursor is made visible. Default: `true`
|
|
1530
1545
|
|
|
1531
1546
|
Changes the visibility of the mouse cursor.
|
|
1532
1547
|
|
|
1533
1548
|
### sdl.mouse.hideCursor()
|
|
1534
1549
|
|
|
1535
|
-
Equivalent to [`sdl.mouse.showCursor
|
|
1550
|
+
Equivalent to [`sdl.mouse.showCursor(false)`](#sdlmouseshowcursorshow).
|
|
1536
1551
|
|
|
1537
1552
|
### sdl.mouse.redrawCursor()
|
|
1538
1553
|
|
|
@@ -1540,7 +1555,7 @@ Forces a cursor redraw.
|
|
|
1540
1555
|
|
|
1541
1556
|
### sdl.mouse.capture([capture])
|
|
1542
1557
|
|
|
1543
|
-
* `capture: <boolean>` If `true` the mouse
|
|
1558
|
+
* `capture: <boolean>` If `true` the mouse is to be captured by the current window. Default: `true`
|
|
1544
1559
|
|
|
1545
1560
|
When the mouse has been captured you will continue receiving mouse events even if the mouse is not over a window.
|
|
1546
1561
|
|
|
@@ -1604,13 +1619,13 @@ When this event is emitted, all instances that were opened from the removed devi
|
|
|
1604
1619
|
* `<object>[]`
|
|
1605
1620
|
* `id: <number>` The unique id for the device.
|
|
1606
1621
|
* `name: <string>` The name of the device.
|
|
1607
|
-
* `path: <string>` The implementation dependent path of the device.
|
|
1608
|
-
* `
|
|
1609
|
-
* `
|
|
1610
|
-
* `vendor: <number>|<null>` The USB vendor ID of the device
|
|
1611
|
-
* `product: <number>|<null>` The USB product ID of the device
|
|
1612
|
-
* `version: <number>|<null>` The USB product version of the device
|
|
1613
|
-
* `player: <number>|<null>` The player index for the device
|
|
1622
|
+
* `path: <string>|<null>` The implementation dependent path of the device, or `null` if it can't be determined.
|
|
1623
|
+
* `type: <JoystickType>|<null>` The type of the device, or `null` if it can't be determined.
|
|
1624
|
+
* `guid: <string>|<null>` The GUID of the device, or `null` if it can't be determined.
|
|
1625
|
+
* `vendor: <number>|<null>` The USB vendor ID of the device, or `null` if it can't be determined.
|
|
1626
|
+
* `product: <number>|<null>` The USB product ID of the device, or `null` if it can't be determined.
|
|
1627
|
+
* `version: <number>|<null>` The USB product version of the device, or `null` if it can't be determined.
|
|
1628
|
+
* `player: <number>|<null>` The player index for the device, or `null` if it can't be determined.
|
|
1614
1629
|
|
|
1615
1630
|
A list of all the detected joystick devices.
|
|
1616
1631
|
|
|
@@ -1648,15 +1663,15 @@ Sample output:
|
|
|
1648
1663
|
|
|
1649
1664
|
### sdl.joystick.openDevice(device)
|
|
1650
1665
|
|
|
1651
|
-
* `device: <object>` An object from [`sdl.joystick.devices`](#sdljoystickdevices) that
|
|
1666
|
+
* `device: <object>` An object from [`sdl.joystick.devices`](#sdljoystickdevices) that is to be opened.
|
|
1652
1667
|
* Returns: [`<joystickInstance>`](#class-joystickinstance) an object representing the opened joystick device instance.
|
|
1653
1668
|
|
|
1654
1669
|
Initializes a joystick device and returns a corresponding instance.
|
|
1655
1670
|
|
|
1656
|
-
## class
|
|
1671
|
+
## class joystickInstance
|
|
1657
1672
|
|
|
1658
|
-
|
|
1659
|
-
Instead, objects returned by [`sdl.joystick.openDevice()`](#sdljoystickopendevicedevice) are of
|
|
1673
|
+
The `JoystickInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
1674
|
+
Instead, objects returned by [`sdl.joystick.openDevice()`](#sdljoystickopendevicedevice) are of type `JoystickInstance`.
|
|
1660
1675
|
|
|
1661
1676
|
<a id="joystick-instance-event-axismotion"></a>
|
|
1662
1677
|
|
|
@@ -1709,19 +1724,19 @@ Handle cleanup here.
|
|
|
1709
1724
|
|
|
1710
1725
|
* `<object>`
|
|
1711
1726
|
|
|
1712
|
-
The [device](#sdljoystickdevices) from which
|
|
1727
|
+
The [device](#sdljoystickdevices) from which the instance was opened.
|
|
1713
1728
|
|
|
1714
1729
|
### joystickInstance.firmwareVersion
|
|
1715
1730
|
|
|
1716
1731
|
* `<number>|<null>`
|
|
1717
1732
|
|
|
1718
|
-
The joystick's firmware version, or `null` if it
|
|
1733
|
+
The joystick's firmware version, or `null` if it is not available.
|
|
1719
1734
|
|
|
1720
1735
|
### joystickInstance.serialNumber
|
|
1721
1736
|
|
|
1722
1737
|
* `<string>|<null>`
|
|
1723
1738
|
|
|
1724
|
-
The joystick's serial number, or `null` if it
|
|
1739
|
+
The joystick's serial number, or `null` if it is not available.
|
|
1725
1740
|
|
|
1726
1741
|
### joystickInstance.axes
|
|
1727
1742
|
|
|
@@ -1744,7 +1759,7 @@ An array of values, each corresponding to the position of one of the joystick's
|
|
|
1744
1759
|
* `<boolean>[]`
|
|
1745
1760
|
|
|
1746
1761
|
An array of values, each corresponding to the state of one of the joystick's buttons.
|
|
1747
|
-
|
|
1762
|
+
Each value in the object isarray is either `true` if the corresponding button is pressed, or `false` otherwise.
|
|
1748
1763
|
|
|
1749
1764
|
### joystickInstance.hats
|
|
1750
1765
|
|
|
@@ -1762,7 +1777,7 @@ The current power level of the joystick device, or `null` if it is unknown.
|
|
|
1762
1777
|
|
|
1763
1778
|
* `index: <number>` The player index to assign to the joystick.
|
|
1764
1779
|
|
|
1765
|
-
Sets the player index of
|
|
1780
|
+
Sets the player index of the joystick.
|
|
1766
1781
|
|
|
1767
1782
|
### joystickInstance.resetPlayer()
|
|
1768
1783
|
|
|
@@ -1772,7 +1787,7 @@ Clears player assignment and player led.
|
|
|
1772
1787
|
|
|
1773
1788
|
* `<boolean>`
|
|
1774
1789
|
|
|
1775
|
-
|
|
1790
|
+
Is `true` if the joystick has a LED light whose color can be controlled.
|
|
1776
1791
|
|
|
1777
1792
|
### joystickInstance.setLed(red, green, blue)
|
|
1778
1793
|
|
|
@@ -1786,9 +1801,9 @@ Sets the color of the LED light on the joystick.
|
|
|
1786
1801
|
|
|
1787
1802
|
* `<boolean>`
|
|
1788
1803
|
|
|
1789
|
-
|
|
1804
|
+
Is `true` if the joystick has rumble motors.
|
|
1790
1805
|
|
|
1791
|
-
### joystickInstance.rumble([low, [
|
|
1806
|
+
### joystickInstance.rumble([low[, high[, duration]]])
|
|
1792
1807
|
|
|
1793
1808
|
* `low: <number>` The intensity of the low frequency rumble motor, from `0` to `1`. Default: `1`
|
|
1794
1809
|
* `high: <number>` The intensity of the high frequency rumble motor, from `0` to `1`. Default: `1`
|
|
@@ -1800,15 +1815,15 @@ Calling this function again before `duration` has ran out, overrides the previou
|
|
|
1800
1815
|
### joystickInstance.stopRumble()
|
|
1801
1816
|
|
|
1802
1817
|
Stops the joystick rumbling.
|
|
1803
|
-
Equivalent to `joystickInstance.rumble(0, 0)
|
|
1818
|
+
Equivalent to [`joystickInstance.rumble(0, 0)`](#joystickinstancerumblelow-high-duration).
|
|
1804
1819
|
|
|
1805
1820
|
### joystickInstance.hasRumbleTriggers
|
|
1806
1821
|
|
|
1807
1822
|
* `<boolean>`
|
|
1808
1823
|
|
|
1809
|
-
|
|
1824
|
+
Is `true` if the joystick has rumble motors on the triggers.
|
|
1810
1825
|
|
|
1811
|
-
### joystickInstance.rumbleTriggers([left, [
|
|
1826
|
+
### joystickInstance.rumbleTriggers([left[, right[, duration]]])
|
|
1812
1827
|
|
|
1813
1828
|
* `left: <number>` The intensity of the left trigger rumble motor, from `0` to `1`. Default: `1`
|
|
1814
1829
|
* `right: <number>` The intensity of the right trigger rumble motor, from `0` to `1`. Default: `1`
|
|
@@ -1820,14 +1835,14 @@ Calling this function again before `duration` has ran out, overrides the previou
|
|
|
1820
1835
|
### joystickInstance.stopRumbleTriggers()
|
|
1821
1836
|
|
|
1822
1837
|
Stops the joystick trigger rumbling.
|
|
1823
|
-
Equivalent to `joystickInstance.rumbleTriggers(0, 0)
|
|
1838
|
+
Equivalent to [`joystickInstance.rumbleTriggers(0, 0)`](#joystickinstancerumbletriggersleft-right-duration).
|
|
1824
1839
|
|
|
1825
1840
|
### joystickInstance.closed
|
|
1826
1841
|
|
|
1827
1842
|
* `<boolean>`
|
|
1828
1843
|
|
|
1829
|
-
|
|
1830
|
-
A closed instance object
|
|
1844
|
+
Is `true` if the instance is closed.
|
|
1845
|
+
A closed instance object must not be used any further.
|
|
1831
1846
|
|
|
1832
1847
|
### joystickInstance.close()
|
|
1833
1848
|
|
|
@@ -1843,10 +1858,10 @@ With a pure joystick instance it's impossible to know which axis or button corre
|
|
|
1843
1858
|
|
|
1844
1859
|
Because controllers are an abstraction over joysticks, they operate on the same set of devices (if a joystick device and a controller device have the same id, then they refer to the same underlying physical device).
|
|
1845
1860
|
For a joystick device to also be available as a controller device it needs a "mapping".
|
|
1846
|
-
A mapping is a string that consists of the device's GUID,
|
|
1861
|
+
A mapping is a string that consists of the device's GUID, its name, and a series of pairings between one joystick axis/button and the corresponding controller axis/button name.
|
|
1847
1862
|
See the sample output [`here`](#sdlcontrollerdevices) for an example.
|
|
1848
1863
|
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.
|
|
1849
|
-
|
|
1864
|
+
Add them via:
|
|
1850
1865
|
|
|
1851
1866
|
```js
|
|
1852
1867
|
const url = 'https://raw.githubusercontent.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt'
|
|
@@ -1880,21 +1895,21 @@ When this event is emitted, all instances that were opened from the removed devi
|
|
|
1880
1895
|
* `mappings: <string>[]` An array of mappings to register.
|
|
1881
1896
|
|
|
1882
1897
|
Registers new mappings for controllers.
|
|
1883
|
-
This
|
|
1898
|
+
This may cause already opened controller instances to be [remapped](#event-remap).
|
|
1884
1899
|
|
|
1885
1900
|
### sdl.controller.devices
|
|
1886
1901
|
|
|
1887
1902
|
* `<object>[]`
|
|
1888
1903
|
* `id: <number>` The unique id for the device.
|
|
1889
1904
|
* `name: <string>` The name of the device.
|
|
1890
|
-
* `path: <string>` The implementation dependent path of the device.
|
|
1891
|
-
* `
|
|
1892
|
-
* `
|
|
1893
|
-
* `vendor: <number>|<null>` The USB vendor ID of the device
|
|
1894
|
-
* `product: <number>|<null>` The USB product ID of the device
|
|
1895
|
-
* `version: <number>|<null>` The USB product version of the device
|
|
1896
|
-
* `player: <number>|<null>` The player index for the device
|
|
1897
|
-
* `mapping: <string>` The axis and button mapping for
|
|
1905
|
+
* `path: <string>|<null>` The implementation dependent path of the device, or `null` if it can't be determined.
|
|
1906
|
+
* `type: <string>|<null>` The type of the device, or `null` if it can't be determined.
|
|
1907
|
+
* `guid: <string>|<null>` The GUID of the device, or `null` if it can't be determined.
|
|
1908
|
+
* `vendor: <number>|<null>` The USB vendor ID of the device, or `null` if it can't be determined.
|
|
1909
|
+
* `product: <number>|<null>` The USB product ID of the device, or `null` if it can't be determined.
|
|
1910
|
+
* `version: <number>|<null>` The USB product version of the device, or `null` if it can't be determined.
|
|
1911
|
+
* `player: <number>|<null>` The player index for the device, or `null` if it can't be determined.
|
|
1912
|
+
* `mapping: <string>|<null>` The axis and button mapping for the device, or `null` if it can't be determined.
|
|
1898
1913
|
|
|
1899
1914
|
A list of all the detected controller devices.
|
|
1900
1915
|
|
|
@@ -1937,15 +1952,15 @@ Sample output:
|
|
|
1937
1952
|
|
|
1938
1953
|
### sdl.controller.openDevice(device)
|
|
1939
1954
|
|
|
1940
|
-
* `device: <object>` An object from [`sdl.controller.devices`](#sdlcontrollerdevices) that
|
|
1955
|
+
* `device: <object>` An object from [`sdl.controller.devices`](#sdlcontrollerdevices) that is to be opened.
|
|
1941
1956
|
* Returns: [`<ControllerInstance>`](#class-controllerinstance) an object representing the opened controller device instance.
|
|
1942
1957
|
|
|
1943
1958
|
Initializes an controller device and returns a corresponding instance.
|
|
1944
1959
|
|
|
1945
1960
|
## class ControllerInstance
|
|
1946
1961
|
|
|
1947
|
-
|
|
1948
|
-
Instead, objects returned by [`sdl.controller.openDevice()`](#sdlcontrolleropendevicedevice) are of
|
|
1962
|
+
The `ControllerInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
1963
|
+
Instead, objects returned by [`sdl.controller.openDevice()`](#sdlcontrolleropendevicedevice) are of type `ControllerInstance`.
|
|
1949
1964
|
|
|
1950
1965
|
<a id="controller-instance-event-axismotion"></a>
|
|
1951
1966
|
|
|
@@ -1974,8 +1989,8 @@ Fired when one of the controller's buttons is released.
|
|
|
1974
1989
|
|
|
1975
1990
|
### Event: 'remap'
|
|
1976
1991
|
|
|
1977
|
-
Fired when a new mapping for
|
|
1978
|
-
This
|
|
1992
|
+
Fired when a new mapping for the controller is applied (usually via [`sdl.controller.addMappings()`](#sdlcontrolleraddmappingsmappings)).
|
|
1993
|
+
This may cause all of the controller's axes and buttons to aquire new values.
|
|
1979
1994
|
|
|
1980
1995
|
<a id="controller-instance-event-close"></a>
|
|
1981
1996
|
|
|
@@ -1988,7 +2003,7 @@ Handle cleanup here.
|
|
|
1988
2003
|
|
|
1989
2004
|
* `<object>`
|
|
1990
2005
|
|
|
1991
|
-
The [device](#sdlcontrollerdevices) from which
|
|
2006
|
+
The [device](#sdlcontrollerdevices) from which the instance was opened.
|
|
1992
2007
|
|
|
1993
2008
|
### controllerInstance.firmwareVersion
|
|
1994
2009
|
|
|
@@ -2000,14 +2015,14 @@ The controller's firmware version.
|
|
|
2000
2015
|
|
|
2001
2016
|
* `<string>|<null>`
|
|
2002
2017
|
|
|
2003
|
-
The controller's serial number, or `null` if it
|
|
2018
|
+
The controller's serial number, or `null` if it is not available.
|
|
2004
2019
|
|
|
2005
2020
|
### controllerInstance.steamHandle
|
|
2006
2021
|
|
|
2007
2022
|
* `<Buffer>|<null>`
|
|
2008
2023
|
|
|
2009
|
-
The controller's steam handle, or `null` if it
|
|
2010
|
-
The `Buffer`
|
|
2024
|
+
The controller's steam handle, or `null` if it is not available.
|
|
2025
|
+
The `Buffer` contains an `InputHandle_t` for the controller that can be used with the [Steam Input API](https://partner.steamgames.com/doc/api/ISteamInput)
|
|
2011
2026
|
|
|
2012
2027
|
### controllerInstance.axes
|
|
2013
2028
|
|
|
@@ -2047,7 +2062,7 @@ It may be necessary to impose certain tolerances on these values to account for
|
|
|
2047
2062
|
* `paddle4: <boolean>` Paddle 4 pressed
|
|
2048
2063
|
|
|
2049
2064
|
An object mapping each of the controller's buttons to a boolean value.
|
|
2050
|
-
|
|
2065
|
+
Each value in the object is either `true` if the corresponding button is pressed, or `false` otherwise.
|
|
2051
2066
|
|
|
2052
2067
|
### controllerInstance.power
|
|
2053
2068
|
|
|
@@ -2059,7 +2074,7 @@ The current power level of the joystick device, or `null` if it is unknown.
|
|
|
2059
2074
|
|
|
2060
2075
|
* `index: <number>` The player index to assign to the controller.
|
|
2061
2076
|
|
|
2062
|
-
Sets the player index of
|
|
2077
|
+
Sets the player index of the controller.
|
|
2063
2078
|
|
|
2064
2079
|
### controllerInstance.resetPlayer()
|
|
2065
2080
|
|
|
@@ -2069,7 +2084,7 @@ Clears player assignment and player led.
|
|
|
2069
2084
|
|
|
2070
2085
|
* `<boolean>`
|
|
2071
2086
|
|
|
2072
|
-
|
|
2087
|
+
Is `true` if the controller has a LED light whose color can be controlled.
|
|
2073
2088
|
|
|
2074
2089
|
### controllerInstance.setLed(red, green, blue)
|
|
2075
2090
|
|
|
@@ -2083,9 +2098,9 @@ Sets the color of the LED light on the controller.
|
|
|
2083
2098
|
|
|
2084
2099
|
* `<boolean>`
|
|
2085
2100
|
|
|
2086
|
-
|
|
2101
|
+
Is `true` if the controller has rumble motors.
|
|
2087
2102
|
|
|
2088
|
-
### controllerInstance.rumble([low, [
|
|
2103
|
+
### controllerInstance.rumble([low[, high[, duration]]])
|
|
2089
2104
|
|
|
2090
2105
|
* `low: <number>` The intensity of the low frequency rumble motor, from `0` to `1`. Default: `1`
|
|
2091
2106
|
* `high: <number>` The intensity of the high frequency rumble motor, from `0` to `1`. Default: `1`
|
|
@@ -2097,15 +2112,15 @@ Calling this function again before `duration` has ran out, overrides the previou
|
|
|
2097
2112
|
### controllerInstance.stopRumble()
|
|
2098
2113
|
|
|
2099
2114
|
Stops the controller rumbling.
|
|
2100
|
-
Equivalent to `controllerInstance.rumble(0, 0)
|
|
2115
|
+
Equivalent to [`controllerInstance.rumble(0, 0)`](#controllerinstancerumblelow-high-duration).
|
|
2101
2116
|
|
|
2102
2117
|
### controllerInstance.hasRumbleTriggers
|
|
2103
2118
|
|
|
2104
2119
|
* `<boolean>`
|
|
2105
2120
|
|
|
2106
|
-
|
|
2121
|
+
Is `true` if the controller has rumble motors on the triggers.
|
|
2107
2122
|
|
|
2108
|
-
### controllerInstance.rumbleTriggers([left, [
|
|
2123
|
+
### controllerInstance.rumbleTriggers([left[, right[, duration]]])
|
|
2109
2124
|
|
|
2110
2125
|
* `left: <number>` The intensity of the left trigger rumble motor, from `0` to `1`. Default: `1`
|
|
2111
2126
|
* `right: <number>` The intensity of the right trigger rumble motor, from `0` to `1`. Default: `1`
|
|
@@ -2117,14 +2132,14 @@ Calling this function again before `duration` has ran out, overrides the previou
|
|
|
2117
2132
|
### controllerInstance.stopRumbleTriggers()
|
|
2118
2133
|
|
|
2119
2134
|
Stops the controller trigger rumbling.
|
|
2120
|
-
Equivalent to `controllerInstance.rumbleTriggers(0, 0)
|
|
2135
|
+
Equivalent to [`controllerInstance.rumbleTriggers(0, 0)`](#controllerinstancerumbletriggersleft-right-duration).
|
|
2121
2136
|
|
|
2122
2137
|
### controllerInstance.closed
|
|
2123
2138
|
|
|
2124
2139
|
* `<boolean>`
|
|
2125
2140
|
|
|
2126
|
-
|
|
2127
|
-
A closed instance object
|
|
2141
|
+
Is `true` if the instance is closed.
|
|
2142
|
+
A closed instance object must not be used any further.
|
|
2128
2143
|
|
|
2129
2144
|
### controllerInstance.close()
|
|
2130
2145
|
|
|
@@ -2137,33 +2152,38 @@ Closes the instance.
|
|
|
2137
2152
|
|
|
2138
2153
|
* `<number>`
|
|
2139
2154
|
|
|
2140
|
-
|
|
2141
|
-
|
|
2155
|
+
Accelerometers are affected by the force of gravity:
|
|
2156
|
+
even if the device is completely at rest, it will still indicata an acceleration with a magnitude of [`sdl.sensor.STANDARD_GRAVITY`](#sdlsensorstandard_gravity) away from the center of the earth.
|
|
2157
|
+
Use the `sdl.sensor.STANDARD_GRAVITY` constant to correct for gravitational acceleration if your application requires it.
|
|
2142
2158
|
|
|
2143
2159
|
### sdl.sensor.devices
|
|
2144
2160
|
|
|
2145
2161
|
* `<object>[]`
|
|
2146
2162
|
* `id: <number>` The unique id of the device.
|
|
2147
2163
|
* `name: <string>` The name of the device.
|
|
2148
|
-
* `type: <string>|<null>` Either `'accelerometer'
|
|
2149
|
-
* `side: <string>|<null>`
|
|
2164
|
+
* `type: <string>|<null>` Either `'accelerometer'` or `'gyroscope'`. Is `null` if it can't be determined.
|
|
2165
|
+
* `side: <string>|<null>` Either `'left'` or `'right'`. Is `null` if the sensor does not have a side, or the value can't be determined.
|
|
2150
2166
|
|
|
2151
2167
|
A list of all the detected sensor devices.
|
|
2168
|
+
|
|
2169
|
+
Some sensors have a `side`, sucha as those on the Joy-Con controller.
|
|
2170
|
+
For most other sensors `side` is `null`.
|
|
2171
|
+
|
|
2152
2172
|
Sample output:
|
|
2153
2173
|
|
|
2154
2174
|
// TODO
|
|
2155
2175
|
|
|
2156
2176
|
### sdl.sensor.openDevice(device)
|
|
2157
2177
|
|
|
2158
|
-
* `device: <object>` An object from [`sdl.sensor.devices`](#sdlsensordevices) that
|
|
2178
|
+
* `device: <object>` An object from [`sdl.sensor.devices`](#sdlsensordevices) that is to be opened.
|
|
2159
2179
|
* Returns: [`<SensorInstance>`](#class-sensorinstance) an object representing the opened sensor device instance.
|
|
2160
2180
|
|
|
2161
2181
|
Initializes a sensor device and returns a corresponding instance.
|
|
2162
2182
|
|
|
2163
2183
|
## class SensorInstance
|
|
2164
2184
|
|
|
2165
|
-
|
|
2166
|
-
Instead, objects returned by [`sdl.sensor.openDevice()`](#sdlsensoropendevicedevice) are of
|
|
2185
|
+
The `SensorInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
2186
|
+
Instead, objects returned by [`sdl.sensor.openDevice()`](#sdlsensoropendevicedevice) are of type `SensorInstance`.
|
|
2167
2187
|
|
|
2168
2188
|
<a id="sensor-instance-event-update"></a>
|
|
2169
2189
|
|
|
@@ -2183,24 +2203,24 @@ Handle cleanup here.
|
|
|
2183
2203
|
|
|
2184
2204
|
* `<object>`
|
|
2185
2205
|
|
|
2186
|
-
The [device](#sdlsensordevices) from which
|
|
2206
|
+
The [device](#sdlsensordevices) from which the `sensorInstance` was opened.
|
|
2187
2207
|
|
|
2188
2208
|
### sensorInstance.data
|
|
2189
2209
|
|
|
2190
2210
|
* `<object>`
|
|
2191
|
-
* `timestamp: <number>|<null>` The time
|
|
2211
|
+
* `timestamp: <number>|<null>` The time the latest measurement was taken __in microseconds__, or `null` if it can't be determined.
|
|
2192
2212
|
* `x: <number>` X axis value.
|
|
2193
2213
|
* `y: <number>` Y axis value.
|
|
2194
2214
|
* `z: <number>` Z axis value.
|
|
2195
2215
|
|
|
2196
2216
|
An object reporting the latest measurement from the sensor.
|
|
2197
2217
|
|
|
2198
|
-
For accelerometers, the values correspond to the current acceleration in meters per second squared.
|
|
2199
|
-
|
|
2218
|
+
For accelerometers, the `x`, `y`, and `z` values correspond to the current acceleration in meters per second squared.
|
|
2219
|
+
Keep in mind the accelerometers are affected by the force of gravity:
|
|
2220
|
+
even if the device is completely at rest, it will still indicata an acceleration with a magnitude of [`sdl.sensor.STANDARD_GRAVITY`](#sdlsensorstandard_gravity) away from the center of the earth.
|
|
2200
2221
|
|
|
2201
|
-
For gyroscopes, the values correspond to the current rate of rotation in radians per second.
|
|
2202
|
-
The rotation is positive in the counter-clockwise direction.
|
|
2203
|
-
That is, an observer looking from a positive location on one of the axes would see positive rotation on that axis when it appeared to be rotating counter-clockwise.
|
|
2222
|
+
For gyroscopes, the `x`, `y`, and `z` values correspond to the current rate of rotation in radians per second.
|
|
2223
|
+
The rotation is positive in the counter-clockwise direction, meaning that an observer looking from a positive location on one of the axes would see positive rotation on that axis when it appeared to be rotating counter-clockwise.
|
|
2204
2224
|
|
|
2205
2225
|
For phones held in portrait mode and game controllers held in front of you, the axes are defined as follows:
|
|
2206
2226
|
* -X ... +X : left ... right
|
|
@@ -2211,8 +2231,8 @@ For phones held in portrait mode and game controllers held in front of you, the
|
|
|
2211
2231
|
|
|
2212
2232
|
* `<boolean>`
|
|
2213
2233
|
|
|
2214
|
-
|
|
2215
|
-
A closed instance object
|
|
2234
|
+
Is `true` if the instance is closed.
|
|
2235
|
+
A closed instance object must not be used any further.
|
|
2216
2236
|
|
|
2217
2237
|
### sensorInstance.close()
|
|
2218
2238
|
|
|
@@ -2232,7 +2252,7 @@ For audio with multiple channels, each point in time is represented by multiple
|
|
|
2232
2252
|
The samples in a frame are arranged as follows:
|
|
2233
2253
|
|
|
2234
2254
|
* For 1 channel (mono) a frame contains just the one sample.
|
|
2235
|
-
* For 2 channels (stereo) the frame
|
|
2255
|
+
* For 2 channels (stereo) the frame contains two samples and the layout is: left, right. This means that the first sample corresponds to the left channel and the second sample corresponds to the right channel.
|
|
2236
2256
|
* For 4 channels (quad) the layout is front-left, front-right, rear-left, rear-right.
|
|
2237
2257
|
* For 6 channels (5.1) the layout is front-left, front-right, center, low-freq, rear-left, rear-right.
|
|
2238
2258
|
|
|
@@ -2319,7 +2339,7 @@ Check [`sdl.audio.devices`](#sdlaudiodevices) to get the new list of audio devic
|
|
|
2319
2339
|
|
|
2320
2340
|
Fired when an existing audio device is removed.
|
|
2321
2341
|
Check [`sdl.audio.devices`](#sdlaudiodevices) to get the new list of audio devices.
|
|
2322
|
-
When
|
|
2342
|
+
When the `'deviceRemove'` event is emitted, all instances that were opened from the removed device are closed automatically.
|
|
2323
2343
|
|
|
2324
2344
|
### sdl.audio.bytesPerSample(format)
|
|
2325
2345
|
|
|
@@ -2385,7 +2405,7 @@ This function is also available from `@kmamal/sdl/helpers`.
|
|
|
2385
2405
|
### sdl.audio.devices
|
|
2386
2406
|
|
|
2387
2407
|
* `<object>[]`
|
|
2388
|
-
* `type: <string>`
|
|
2408
|
+
* `type: <string>` Either `'playback'` or `'recording'`.
|
|
2389
2409
|
* `name: <string>` The name of the device.
|
|
2390
2410
|
|
|
2391
2411
|
A list of all the detected audio devices.
|
|
@@ -2398,8 +2418,8 @@ Sample output for PulseAudio:
|
|
|
2398
2418
|
]
|
|
2399
2419
|
```
|
|
2400
2420
|
|
|
2401
|
-
Note that
|
|
2402
|
-
Despite that, in many common cases, it
|
|
2421
|
+
Note that `sdl.audio.devices` may sometimes be an empty list.
|
|
2422
|
+
Despite that, in many common cases, it's still possible to successfully open the default device by only passing `type` to [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) like this:
|
|
2403
2423
|
|
|
2404
2424
|
```js
|
|
2405
2425
|
const playbackInstance = sdl.audio.openDevice({ type: 'playback' })
|
|
@@ -2408,39 +2428,45 @@ const playbackInstance = sdl.audio.openDevice({ type: 'playback' })
|
|
|
2408
2428
|
### sdl.audio.openDevice(device[, options])
|
|
2409
2429
|
|
|
2410
2430
|
* `device: <object>` An object from [`sdl.audio.devices`](#sdlaudiodevices), or a custom device.
|
|
2411
|
-
* `type: <string>`:
|
|
2431
|
+
* `type: <string>`: Either `'playback'` or `'recording'`.
|
|
2412
2432
|
* `name: <string>|<null>`: The name of the device. Optional.
|
|
2413
2433
|
* `options: <object>`
|
|
2414
2434
|
* `channels: <number>`: Number of audio channels. Valid values: `1`, `2`, `4`, `6`. Default: `1`
|
|
2415
2435
|
* `frequency: <number>`: The sampling frequency in frames per second. Default: `48e3`
|
|
2416
2436
|
* `format: `[`<SampleFormat>`](#sample-formats): The binary format for each sample. Default: `'f32'`
|
|
2417
|
-
* `buffered: <number>`: Number of frames
|
|
2437
|
+
* `buffered: <number>`: Number of frames buffered by the driver. Must be a power of `2`. Default: `4096`
|
|
2418
2438
|
* Returns: [`<AudioInstance>`](#class-audioinstance) an object representing the opened audio device instance.
|
|
2419
2439
|
|
|
2420
2440
|
Initializes an audio device for playback/recording and returns a corresponding instance.
|
|
2421
|
-
If the opened device is a playback device, then
|
|
2441
|
+
If the opened device is a playback device, then it returns an [`AudioPlaybackInstance`](#class-audioplaybackinstance-extends-audioinstance), otherwise it returns an [`AudioRecordingInstance`](#class-audiorecordinginstance-extends-audioinstance).
|
|
2442
|
+
|
|
2443
|
+
Most of the time, you will be passing objects from [`sdl.audio.devices`](#sdlaudiodevices) for the `device` argument:
|
|
2444
|
+
|
|
2445
|
+
```js
|
|
2446
|
+
const device = sdl.audio.devices[selectedIndex]
|
|
2447
|
+
const playbackInstance = sdl.audio.openDevice(device)
|
|
2448
|
+
```
|
|
2422
2449
|
|
|
2423
|
-
|
|
2424
|
-
It is also possible to let SDL pick the most appropriate device by only passing the `type` property without a `name` like this:
|
|
2450
|
+
It's also possible to let SDL pick the most appropriate device by only passing the `type` property:
|
|
2425
2451
|
|
|
2426
2452
|
```js
|
|
2427
2453
|
const playbackInstance = sdl.audio.openDevice({ type: 'playback' })
|
|
2428
2454
|
```
|
|
2429
2455
|
|
|
2430
2456
|
Some audio drivers also support arbitrary and driver-specific strings for the device `name` such as hostname/IP address for a remote audio server, or a filename in the diskaudio driver.
|
|
2431
|
-
These drivers
|
|
2457
|
+
These drivers usually return an empty list for [`sdl.audio.devices`](#sdlaudiodevices).
|
|
2432
2458
|
|
|
2433
|
-
The `channels`, `frequency` and `format` options together define
|
|
2459
|
+
The `channels`, `frequency` and `format` options together define how the data is laid out in the `Buffer` objects that you write to playback instances of read from recording instances.
|
|
2434
2460
|
See also the section on [audio data](#audio-data).
|
|
2435
2461
|
|
|
2436
|
-
The `buffered` option specifies the "delay"
|
|
2437
|
-
With smaller values you
|
|
2438
|
-
Applications such as virtual instruments that need to play audio in reaction to user input
|
|
2462
|
+
The `buffered` option specifies the "delay" between the application and the audio driver.
|
|
2463
|
+
With smaller values you have smaller delays, but you also have to read/write data from/to the driver more frequently.
|
|
2464
|
+
Applications such as virtual instruments that need to play audio in reaction to user input should set `buffered` to a lower value.
|
|
2439
2465
|
|
|
2440
2466
|
|
|
2441
2467
|
## class AudioInstance
|
|
2442
2468
|
|
|
2443
|
-
|
|
2469
|
+
The `AudioInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
2444
2470
|
It only serves as the base class for [`AudioPlaybackInstance`](#class-audioplaybackinstance-extends-audioinstance) and [`AudioRecordingInstance`](#class-audiorecordinginstance-extends-audioinstance).
|
|
2445
2471
|
|
|
2446
2472
|
<a id="audio-instance-event-close"></a>
|
|
@@ -2460,7 +2486,7 @@ A unique identifier for the instance.
|
|
|
2460
2486
|
|
|
2461
2487
|
* `<object>`
|
|
2462
2488
|
|
|
2463
|
-
The device passed to [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) when
|
|
2489
|
+
The device passed to [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) when the `audioInstance` was opened.
|
|
2464
2490
|
|
|
2465
2491
|
### audioInstance.channels
|
|
2466
2492
|
|
|
@@ -2533,7 +2559,7 @@ The buffer size (in frames) the instance was opened with.
|
|
|
2533
2559
|
|
|
2534
2560
|
* `<boolean>`
|
|
2535
2561
|
|
|
2536
|
-
|
|
2562
|
+
Is `true` if the instance is currently playing.
|
|
2537
2563
|
|
|
2538
2564
|
### audioInstance.play([play])
|
|
2539
2565
|
|
|
@@ -2549,7 +2575,7 @@ Equivalent to [`audioInstance.play(false)`](#audioinstanceplayplay)
|
|
|
2549
2575
|
|
|
2550
2576
|
* `<number>`
|
|
2551
2577
|
|
|
2552
|
-
The number of bytes that are currently queued up, waiting to be either played by the
|
|
2578
|
+
The number of bytes that are currently queued up, waiting to be either played by the system or dequeued by the user.
|
|
2553
2579
|
|
|
2554
2580
|
### audioInstance.clearQueue()
|
|
2555
2581
|
|
|
@@ -2559,8 +2585,8 @@ Clears the queued data.
|
|
|
2559
2585
|
|
|
2560
2586
|
* `<boolean>`
|
|
2561
2587
|
|
|
2562
|
-
|
|
2563
|
-
A closed instance object
|
|
2588
|
+
Is `true` if the instance is closed.
|
|
2589
|
+
A closed instance object must not be used any further.
|
|
2564
2590
|
|
|
2565
2591
|
### audioInstance.close()
|
|
2566
2592
|
|
|
@@ -2569,21 +2595,21 @@ Closes the instance.
|
|
|
2569
2595
|
|
|
2570
2596
|
## class AudioPlaybackInstance extends AudioInstance
|
|
2571
2597
|
|
|
2572
|
-
|
|
2573
|
-
Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) are of
|
|
2598
|
+
The `AudioPlaybackInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
2599
|
+
Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) are of type `AudioPlaybackInstance`, if a playback device is opened.
|
|
2574
2600
|
|
|
2575
2601
|
### playbackInstance.enqueue(buffer[, bytes])
|
|
2576
2602
|
|
|
2577
2603
|
* `buffer: <Buffer>` The buffer to read data from.
|
|
2578
2604
|
* `bytes: <number>` The number of bytes to read from the buffer. Default: `buffer.length`
|
|
2579
2605
|
|
|
2580
|
-
Takes
|
|
2606
|
+
Takes the audio data that you have written to the buffer, and writes it to the queue, from where it will be played back as audio.
|
|
2581
2607
|
|
|
2582
2608
|
|
|
2583
2609
|
## class AudioRecordingInstance extends AudioInstance
|
|
2584
2610
|
|
|
2585
|
-
|
|
2586
|
-
Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) are of
|
|
2611
|
+
The `AudioRecordingInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
2612
|
+
Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) are of type `AudioRecordingInstance`, if a recording device is opened.
|
|
2587
2613
|
|
|
2588
2614
|
### recordingInstance.dequeue(buffer[, bytes])
|
|
2589
2615
|
|
|
@@ -2591,7 +2617,7 @@ Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevic
|
|
|
2591
2617
|
* `bytes: <number>` The number of bytes to write to the buffer. Default: `buffer.length`
|
|
2592
2618
|
* Returns: `<number>` The actual number of bytes read.
|
|
2593
2619
|
|
|
2594
|
-
Takes recorded audio data that has
|
|
2620
|
+
Takes recorded audio data that has is waiting on the queue, and writes it to the provided buffer.
|
|
2595
2621
|
|
|
2596
2622
|
|
|
2597
2623
|
## sdl.clipboard
|
|
@@ -2621,23 +2647,27 @@ Changes the text contents of the clipboard.
|
|
|
2621
2647
|
### sdl.power.info
|
|
2622
2648
|
|
|
2623
2649
|
* `<object>`
|
|
2624
|
-
* `state: <string>|<null>` One of `'noBattery'`, `'battery'`, `'charging'`, `'charged'`.
|
|
2625
|
-
* `seconds: <number>|<null>` Seconds of battery life left
|
|
2626
|
-
* `percent: <number>|<null>` Percentage of battery life left
|
|
2650
|
+
* `state: <string>|<null>` One of `'noBattery'`, `'battery'`, `'charging'`, `'charged'`. Is `null` if it can't be determinded.
|
|
2651
|
+
* `seconds: <number>|<null>` Seconds of battery life left, or `null` if not running on battery or if it can't be determinded.
|
|
2652
|
+
* `percent: <number>|<null>` Percentage of battery life left, or `null` if not running on battery or if it can't be determinded.
|
|
2627
2653
|
|
|
2628
2654
|
The curent power information of the device.
|
|
2629
2655
|
|
|
2630
2656
|
|
|
2631
2657
|
## Helpers
|
|
2632
2658
|
|
|
2633
|
-
The `@kmamal/sdl` library
|
|
2659
|
+
The `@kmamal/sdl` library must only be imported from the main thread.
|
|
2634
2660
|
If you try importing it from a `worker_thread` you will get an error.
|
|
2635
|
-
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
|
|
2661
|
+
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 its own instance of the module and it's hard to make them talk with each other).
|
|
2636
2662
|
|
|
2637
2663
|
It's often useful however to offload CPU-heavy work to a thread, so the main thread can respond to input events faster.
|
|
2638
|
-
This is still possible!
|
|
2664
|
+
This is still possible!
|
|
2665
|
+
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.
|
|
2666
|
+
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.
|
|
2639
2667
|
|
|
2640
|
-
Since these are just helpers and don't call any SLD code underneath it's safe to use them.
|
|
2668
|
+
Since these are just helpers and don't call any SLD code underneath it's safe to use them.
|
|
2669
|
+
They are made available through the `@kmamal/sdl/helpers` sub-module that does not load any of the native code.
|
|
2670
|
+
For an example of their use see [this example](https://github.com/kmamal/node-sdl/blob/master/examples/12-audio-thread/audio-worker.js).
|
|
2641
2671
|
|
|
2642
2672
|
The functions included in `@kmamal/sdl/helpers` are:
|
|
2643
2673
|
|
|
@@ -2651,18 +2681,18 @@ The functions included in `@kmamal/sdl/helpers` are:
|
|
|
2651
2681
|
|
|
2652
2682
|
## Building from source
|
|
2653
2683
|
|
|
2654
|
-
If
|
|
2684
|
+
If prebuilt binaries are not available for your platform, `@kmamal/sdl` tries to compile itself during installation.
|
|
2655
2685
|
A few prerequisites are necessary for that to work:
|
|
2656
2686
|
|
|
2657
|
-
First,
|
|
2687
|
+
First, install [node-addon-api](https://github.com/nodejs/node-addon-api) and [node-gyp](https://github.com/nodejs/node-gyp#installation) with all its dependencies.
|
|
2658
2688
|
|
|
2659
|
-
On Mac, you
|
|
2660
|
-
|
|
2689
|
+
On Mac, you also need to install `xquartz` so that SDL can find the X11 headers it needs.
|
|
2690
|
+
The command to install `quartz` via homebrew is `brew install xquartz`.
|
|
2661
2691
|
|
|
2662
2692
|
You don't need to install any SDL libraries or headers.
|
|
2663
|
-
These
|
|
2664
|
-
If `@kmamal/build-sdl` has no prebuilt library for your platform, it
|
|
2665
|
-
You
|
|
2693
|
+
These are downloaded automatically through the [@kmamal/build-sdl](https://github.com/kmamal/build-sdl) package.
|
|
2694
|
+
If `@kmamal/build-sdl` has no prebuilt library for your platform, it tries to compile one on the spot.
|
|
2695
|
+
You need to have `cmake` installed for that to work.
|
|
2666
2696
|
|
|
2667
2697
|
---
|
|
2668
2698
|
|