@kmamal/sdl 0.11.8 → 0.11.10
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 +18 -1
- package/README.md +271 -226
- package/package.json +11 -9
- package/scripts/download-sdl.mjs +3 -3
- 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 +21 -11
- 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 +17 -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>`
|
|
@@ -374,13 +383,21 @@ Check the [`examples/`](https://github.com/kmamal/node-sdl/tree/master/examples#
|
|
|
374
383
|
* `audio: <object>`
|
|
375
384
|
* `all: <string>[]` A list of all audio drivers.
|
|
376
385
|
* `current: <string>|<null>` The audio driver that is currently selected.
|
|
386
|
+
* `initialized: <object>`
|
|
387
|
+
* `video: <boolean>`: Is `true` if the video subsystem was sucessfully initialized, or `false` otherwise.
|
|
388
|
+
* `audio: <boolean>`: Is `true` if the audio subsystem was sucessfully initialized, or `false` otherwise.
|
|
389
|
+
* `joystick: <boolean>`: Is `true` if the joystick subsystem was sucessfully initialized, or `false` otherwise.
|
|
390
|
+
* `controller: <boolean>`: Is `true` if the controller subsystem was sucessfully initialized, or `false` otherwise.
|
|
391
|
+
* `haptic: <boolean>`: Is `true` if the haptic subsystem was sucessfully initialized, or `false` otherwise.
|
|
392
|
+
* `sensor: <boolean>`: Is `true` if the sensor subsystem was sucessfully initialized, or `false` otherwise.
|
|
393
|
+
|
|
394
|
+
The `sdl.info` object is filled with information produced during the initialization of SDL.
|
|
395
|
+
All the values remain constant throughout the execution of the program.
|
|
377
396
|
|
|
378
|
-
|
|
379
|
-
All the values will remain constant throughout the execution of the program.
|
|
380
|
-
If you want to initialize SDL with drivers other than the default ones, you can do so via its [environment variables](https://wiki.libsdl.org/FAQUsingSDL).
|
|
397
|
+
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
398
|
|
|
382
|
-
Note that the `current` video or audio driver
|
|
383
|
-
This
|
|
399
|
+
Note that the `current` video or audio driver may be `null`.
|
|
400
|
+
This usually happens on systems that don't have any compatible devices, such as on a CI pipeline.
|
|
384
401
|
|
|
385
402
|
Sample data for Ubuntu:
|
|
386
403
|
|
|
@@ -401,6 +418,14 @@ Sample data for Ubuntu:
|
|
|
401
418
|
current: 'pulseaudio',
|
|
402
419
|
},
|
|
403
420
|
},
|
|
421
|
+
initialized: {
|
|
422
|
+
video: true,
|
|
423
|
+
audio: true,
|
|
424
|
+
joystick: true,
|
|
425
|
+
controller: true,
|
|
426
|
+
haptic: true,
|
|
427
|
+
sensor: true,
|
|
428
|
+
},
|
|
404
429
|
}
|
|
405
430
|
```
|
|
406
431
|
|
|
@@ -409,7 +434,7 @@ Sample data for Ubuntu:
|
|
|
409
434
|
|
|
410
435
|
### Image data
|
|
411
436
|
|
|
412
|
-
There are 3 places in the API where you
|
|
437
|
+
There are 3 places in the API where you must provide an image to the library:
|
|
413
438
|
|
|
414
439
|
* [`window.render()`](#windowrenderwidth-height-stride-format-buffer-options)
|
|
415
440
|
* [`window.setIcon()`](#windowseticonwidth-height-stride-format-buffer)
|
|
@@ -419,11 +444,11 @@ All three of these functions accept the image as a series of arguments:
|
|
|
419
444
|
|
|
420
445
|
* `width: <number>` The width of the image in pixels.
|
|
421
446
|
* `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.
|
|
447
|
+
* `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
448
|
* `format: `[`<PixelFormat>`](#pixel-formats) The binary representation of the data in the buffer.
|
|
424
449
|
* `buffer: <Buffer>` Holds the actual pixel data for the image, in the format and layout specified by all the above arguments.
|
|
425
450
|
|
|
426
|
-
So for example, to fill the window with a red+green gradient you could do:
|
|
451
|
+
So, for example, to fill the window with a red+green gradient you could do:
|
|
427
452
|
|
|
428
453
|
```js
|
|
429
454
|
const { pixelWidth: width, pixelHeight: height } = window
|
|
@@ -445,11 +470,12 @@ window.render(width, height, stride, 'rgba32', buffer)
|
|
|
445
470
|
|
|
446
471
|
### High-DPI
|
|
447
472
|
|
|
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
|
|
473
|
+
On a high-dpi display, windows have more pixels than their `width` and `height` would indicate.
|
|
474
|
+
On such systems `width` and `height` (and all other measurements such as `x` and `y`) are measured in "points" instead of pixels.
|
|
475
|
+
Points are an abstract unit of measurement and don't necessarily correspond to pixels.
|
|
476
|
+
If you need to work with pixels, you can use the window's `pixelWidth` and `pixelHeight` properties.
|
|
477
|
+
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.
|
|
478
|
+
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
479
|
|
|
454
480
|
### Pixel formats
|
|
455
481
|
|
|
@@ -526,7 +552,7 @@ Fired when a display changes position.
|
|
|
526
552
|
### sdl.video.displays
|
|
527
553
|
|
|
528
554
|
* `<object>[]`
|
|
529
|
-
* `name: <string>` The name of the display.
|
|
555
|
+
* `name: <string>|<null>` The name of the display, or `null` if it can't be determined.
|
|
530
556
|
* `format: `[`<PixelFormat>`](#pixel-formats) The pixel format of the display.
|
|
531
557
|
* `frequency: <number>` The refresh rate of the display.
|
|
532
558
|
* `geometry: <object>` The desktop region represented by the display.
|
|
@@ -561,7 +587,7 @@ Notice how the geometries don't overlap:
|
|
|
561
587
|
frequency: 60,
|
|
562
588
|
geometry: { x: 0, y: 0, width: 1920, height: 1080 },
|
|
563
589
|
usable: { x: 0, y: 27, width: 1920, height: 1053 },
|
|
564
|
-
dpi: { horizontal: 141.76, vertical: 142.13, diagonal: 141.85 }
|
|
590
|
+
dpi: { horizontal: 141.76, vertical: 142.13, diagonal: 141.85 },
|
|
565
591
|
},
|
|
566
592
|
{
|
|
567
593
|
name: '1',
|
|
@@ -569,7 +595,7 @@ Notice how the geometries don't overlap:
|
|
|
569
595
|
frequency: 60,
|
|
570
596
|
geometry: { x: 1920, y: 0, width: 1920, height: 1080 },
|
|
571
597
|
usable: { x: 1920, y: 27, width: 1920, height: 1053 },
|
|
572
|
-
dpi: { horizontal: 141.76, vertical: 142.13, diagonal: 141.85 }
|
|
598
|
+
dpi: { horizontal: 141.76, vertical: 142.13, diagonal: 141.85 },
|
|
573
599
|
},
|
|
574
600
|
]
|
|
575
601
|
```
|
|
@@ -595,68 +621,68 @@ The window that the mouse is hovered over, or `null` if the mouse is not over a
|
|
|
595
621
|
### sdl.video.createWindow([options])
|
|
596
622
|
|
|
597
623
|
* `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
|
|
624
|
+
* `title: <string>` Appears in the window's title bar. Default: `''`
|
|
625
|
+
* `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]`
|
|
626
|
+
* `x: <number>` The x position in which the window should appear relative to the screen, or `null` for centered. Default: `null`
|
|
627
|
+
* `y: <number>` The y position in which the window should appear relative to the screen, or `null` for centered. Default: `null`
|
|
602
628
|
* `width: <number>` The width of the window. Default: `640`
|
|
603
629
|
* `height: <number>` The height of the window. Default: `480`
|
|
604
630
|
* `visible: <boolean>` Set to `false` to create a hidden window that will only be shown when you call [`window.show()`](#windowshowshow). Default: `true`
|
|
605
631
|
* `fullscreen: <boolean>` Set to `true` to create the window in fullscreen mode. Default: `false`
|
|
606
632
|
* `resizable: <boolean>` Set to `true` to allow resizing the window by dragging its borders. Default: `false`
|
|
607
633
|
* `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
|
|
634
|
+
* `alwaysOnTop: <boolean>` Set to `true` to always show the window above others. Default: `false`
|
|
609
635
|
* `accelerated: <boolean>` Set to `false` to disable hardware accelerated rendering. Default: `true`
|
|
610
636
|
* `vsync: <boolean>` Set to `false` to disable frame rate synchronization. Default: `true`
|
|
611
637
|
* `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
638
|
* `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
|
|
639
|
+
* `skipTaskbar: <boolean>` X11 only. Set to `true` to not add the window to the taskbar. Default: `false`
|
|
640
|
+
* `popupMenu: <boolean>` X11 only. Set to `true` to treat the window like a popup menu. Default: `false`
|
|
641
|
+
* `tooltip: <boolean>` X11 only. Set to `true` to treat the window like a tooltip. Default: `false`
|
|
642
|
+
* `utility: <boolean>` X11 only. Set to `true` to treat the window like a utility window. Default: `false`
|
|
617
643
|
* Returns: [`<Window>`](#class-window) an object representing the new window.
|
|
618
644
|
|
|
619
645
|
Creates a new window.
|
|
620
646
|
|
|
621
647
|
The following restrictions apply:
|
|
622
648
|
|
|
623
|
-
*
|
|
649
|
+
* The `display` option is mutually exclusive with the `x` and `y` options.
|
|
624
650
|
* The `resizable` and `borderless` options are mutually exclusive.
|
|
625
651
|
* The `opengl` and `webgpu` options are mutually exclusive.
|
|
626
652
|
* The `vsync` option only applies to windows that are also `accelerated`.
|
|
627
653
|
* The `accelerated` and `vsync` options have no effect if either `opengl` or `webgpu` is also specified.
|
|
628
654
|
|
|
629
|
-
If you set the `opengl` or `webgpu` options, then you
|
|
655
|
+
If you set the `opengl` or `webgpu` options, then you must use OpenGL/WebGPU calls to render to the window.
|
|
630
656
|
Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-options) will fail.
|
|
631
657
|
|
|
632
658
|
## class Window
|
|
633
659
|
|
|
634
|
-
|
|
635
|
-
Instead, objects returned by [`sdl.video.createWindow()`](#sdlvideocreatewindowoptions) are of
|
|
660
|
+
The `Window` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
661
|
+
Instead, objects returned by [`sdl.video.createWindow()`](#sdlvideocreatewindowoptions) are of type `Window`.
|
|
636
662
|
|
|
637
663
|
### Event: 'show'
|
|
638
664
|
|
|
639
|
-
Fired when
|
|
665
|
+
Fired when the window becomes visible.
|
|
640
666
|
|
|
641
667
|
### Event: 'hide'
|
|
642
668
|
|
|
643
|
-
Fired when
|
|
669
|
+
Fired when the window becomes hidden.
|
|
644
670
|
|
|
645
671
|
### Event: 'expose'
|
|
646
672
|
|
|
647
|
-
Fired when
|
|
673
|
+
Fired when the window becomes exposed and should be redrawn.
|
|
648
674
|
|
|
649
675
|
### Event: 'minimize'
|
|
650
676
|
|
|
651
|
-
Fired when
|
|
677
|
+
Fired when the window becomes minimized.
|
|
652
678
|
|
|
653
679
|
### Event: 'maximize'
|
|
654
680
|
|
|
655
|
-
Fired when
|
|
681
|
+
Fired when the window becomes maximized.
|
|
656
682
|
|
|
657
683
|
### Event: 'restore'
|
|
658
684
|
|
|
659
|
-
Fired when
|
|
685
|
+
Fired when the window gets restored.
|
|
660
686
|
|
|
661
687
|
### Event: 'move'
|
|
662
688
|
|
|
@@ -678,15 +704,15 @@ Fired when the window changes size.
|
|
|
678
704
|
|
|
679
705
|
* `display: <object>` An object from [`sdl.video.displays`](#sdlvideodisplays) indicating the window's new display.
|
|
680
706
|
|
|
681
|
-
Fired when
|
|
707
|
+
Fired when the window moves from one display to another.
|
|
682
708
|
|
|
683
709
|
### Event: 'focus'
|
|
684
710
|
|
|
685
|
-
Fired when
|
|
711
|
+
Fired when the window gains the keyboard focus.
|
|
686
712
|
|
|
687
713
|
### Event: 'blur'
|
|
688
714
|
|
|
689
|
-
Fired when
|
|
715
|
+
Fired when the window loses the keyboard focus.
|
|
690
716
|
|
|
691
717
|
### Event: 'hover'
|
|
692
718
|
|
|
@@ -698,11 +724,11 @@ Fired when the mouse leaves the window.
|
|
|
698
724
|
|
|
699
725
|
### Event: 'beforeClose'
|
|
700
726
|
|
|
701
|
-
* `prevent: <function (void) => void>` Call this to prevent the window from closing.
|
|
727
|
+
* `prevent: <function (void) => void>` Call this function to prevent the window from closing.
|
|
702
728
|
|
|
703
|
-
Fired to indicate that the user
|
|
704
|
-
If you need to display any confirmation dialogs
|
|
705
|
-
If `prevent` is not called, then
|
|
729
|
+
Fired to indicate that the user requested that the window should close (usually by clicking the "x" button).
|
|
730
|
+
If you need to display any confirmation dialogs, call `event.prevent()` and afterwards handle destruction manually.
|
|
731
|
+
If `prevent` is not called, then the `beforeClose` event will be followed by a [`'close'`](#event-close) event.
|
|
706
732
|
|
|
707
733
|
### Event: 'close'
|
|
708
734
|
|
|
@@ -742,13 +768,13 @@ Fired when a key is released.
|
|
|
742
768
|
|
|
743
769
|
* `text: <string>` The unicode representation of the character that was entered.
|
|
744
770
|
|
|
745
|
-
Fired when
|
|
771
|
+
Fired when text is entered via the keyboard.
|
|
746
772
|
|
|
747
773
|
### Event: 'mouseButtonDown'
|
|
748
774
|
|
|
749
775
|
* `x: <number>` The mouse's x position when the event happened, relative to the window.
|
|
750
776
|
* `y: <number>` The mouse's y position when the event happened, relative to the window.
|
|
751
|
-
* `touch: <boolean>`
|
|
777
|
+
* `touch: <boolean>` Is `true` if the event was caused by a touch event.
|
|
752
778
|
* `button: `[`<sdl.mouse.BUTTON>`](#enum-button) The button that was pressed.
|
|
753
779
|
|
|
754
780
|
Fired when a mouse button is pressed.
|
|
@@ -757,7 +783,7 @@ Fired when a mouse button is pressed.
|
|
|
757
783
|
|
|
758
784
|
* `x: <number>` The mouse's x position when the event happened, relative to the window.
|
|
759
785
|
* `y: <number>` The mouse's y position when the event happened, relative to the window.
|
|
760
|
-
* `touch: <boolean>`
|
|
786
|
+
* `touch: <boolean>` Is `true` if the event was caused by a touch event.
|
|
761
787
|
* `button: `[`<sdl.mouse.BUTTON>`](#enum-button) The button that was released.
|
|
762
788
|
|
|
763
789
|
Fired when a mouse button is released.
|
|
@@ -766,7 +792,7 @@ Fired when a mouse button is released.
|
|
|
766
792
|
|
|
767
793
|
* `x: <number>` The mouse's x position when the event happened, relative to the window.
|
|
768
794
|
* `y: <number>` The mouse's y position when the event happened, relative to the window.
|
|
769
|
-
* `touch: <boolean>`
|
|
795
|
+
* `touch: <boolean>` Is `true` if the event was caused by a touch event.
|
|
770
796
|
|
|
771
797
|
Fired when the mouse moves.
|
|
772
798
|
|
|
@@ -774,16 +800,16 @@ Fired when the mouse moves.
|
|
|
774
800
|
|
|
775
801
|
* `x: <number>` The mouse's x position when the event happened, relative to the window.
|
|
776
802
|
* `y: <number>` The mouse's y position when the event happened, relative to the window.
|
|
777
|
-
* `touch: <boolean>`
|
|
803
|
+
* `touch: <boolean>` Is `true` if the event was caused by a touch event.
|
|
778
804
|
* `dx: <number>` The wheel's x movement, relative to its last position.
|
|
779
805
|
* `dy: <number>` The wheel's y movement, relative to its last position.
|
|
780
|
-
* `flipped: <boolean>`
|
|
806
|
+
* `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
807
|
|
|
782
808
|
Fired when the mouse wheel is scrolled.
|
|
783
809
|
|
|
784
810
|
### Event: 'dropBegin'
|
|
785
811
|
|
|
786
|
-
When
|
|
812
|
+
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
813
|
|
|
788
814
|
### Event: 'dropText'
|
|
789
815
|
|
|
@@ -854,13 +880,15 @@ The window's height.
|
|
|
854
880
|
|
|
855
881
|
* `<number>`
|
|
856
882
|
|
|
857
|
-
The window's width in pixels.
|
|
883
|
+
The window's width in pixels.
|
|
884
|
+
Is larger than [`width`](#windowwidth) on [high-dpi](#high-dpi) displays.
|
|
858
885
|
|
|
859
886
|
### window.pixelHeight
|
|
860
887
|
|
|
861
888
|
* `<number>`
|
|
862
889
|
|
|
863
|
-
The window's height in pixels.
|
|
890
|
+
The window's height in pixels.
|
|
891
|
+
Is larger than [`height`](#windowheight) on [high-dpi](#high-dpi) displays.
|
|
864
892
|
|
|
865
893
|
### window.setSize(width, height)
|
|
866
894
|
|
|
@@ -881,14 +909,14 @@ This function only behaves differently from [`window.setSize()`](#windowsetsizew
|
|
|
881
909
|
|
|
882
910
|
* `<object>`
|
|
883
911
|
|
|
884
|
-
An object from [`sdl.video.displays`](#sdlvideodisplays) indicating the display
|
|
885
|
-
If the window spans multiple displays, then the display
|
|
912
|
+
An object from [`sdl.video.displays`](#sdlvideodisplays) indicating the display the window belongs to.
|
|
913
|
+
If the window spans multiple displays, then the display that contains the center of the window is returned.
|
|
886
914
|
|
|
887
915
|
### window.visible
|
|
888
916
|
|
|
889
917
|
* `<boolean>`
|
|
890
918
|
|
|
891
|
-
|
|
919
|
+
Is `true` if the window is visible.
|
|
892
920
|
|
|
893
921
|
### window.show([show])
|
|
894
922
|
|
|
@@ -904,7 +932,7 @@ Equivalent to [`window.show(false)`](#windowshowshow).
|
|
|
904
932
|
|
|
905
933
|
* `<boolean>`
|
|
906
934
|
|
|
907
|
-
|
|
935
|
+
Is `true` if the window is fullscreen.
|
|
908
936
|
A fullscreen window is displayed over the entire screen.
|
|
909
937
|
|
|
910
938
|
### window.setFullscreen(fullscreen)
|
|
@@ -917,8 +945,8 @@ Changes the window's fullscreen property.
|
|
|
917
945
|
|
|
918
946
|
* `<boolean>`
|
|
919
947
|
|
|
920
|
-
|
|
921
|
-
A resizable window can be resized by dragging
|
|
948
|
+
Is `true` if the window is resizable.
|
|
949
|
+
A resizable window can be resized by dragging its borders.
|
|
922
950
|
|
|
923
951
|
### window.setResizable(resizable)
|
|
924
952
|
|
|
@@ -930,7 +958,7 @@ Changes the window's resizable property.
|
|
|
930
958
|
|
|
931
959
|
* `<boolean>`
|
|
932
960
|
|
|
933
|
-
|
|
961
|
+
Is `true` if the window is borderless.
|
|
934
962
|
A borderless window has no borders or title bar.
|
|
935
963
|
|
|
936
964
|
### window.setBorderless(borderless)
|
|
@@ -943,14 +971,14 @@ Changes the window's borderless property.
|
|
|
943
971
|
|
|
944
972
|
* `<boolean>`
|
|
945
973
|
|
|
946
|
-
|
|
947
|
-
Such a window
|
|
974
|
+
Is `true` if the window was created with `alwaysOnTop: true`.
|
|
975
|
+
Such a window is always be shown above other windows.
|
|
948
976
|
|
|
949
977
|
### window.accelerated
|
|
950
978
|
|
|
951
979
|
* `<boolean>`
|
|
952
980
|
|
|
953
|
-
|
|
981
|
+
Is `true` if the window is using hardware accelerated rendering.
|
|
954
982
|
|
|
955
983
|
### window.setAccelerated(accelerated)
|
|
956
984
|
|
|
@@ -964,9 +992,9 @@ If you have set the `opengl` or `webgpu` options, then calls to this function wi
|
|
|
964
992
|
|
|
965
993
|
* `<boolean>`
|
|
966
994
|
|
|
967
|
-
|
|
968
|
-
|
|
969
|
-
Note that vsync can only be
|
|
995
|
+
Is `true` if the window is using vsync.
|
|
996
|
+
Vsync synchronizes the window's frame rate with the display's refresh rate to prevent tearing.
|
|
997
|
+
Note that vsync can only be set to `true` if [`accelerated`](#windowaccelerated) is also `true`.
|
|
970
998
|
|
|
971
999
|
### window.setVsync(vsync)
|
|
972
1000
|
|
|
@@ -980,16 +1008,16 @@ If you have set the `opengl` or `webgpu` options, then calls to this function wi
|
|
|
980
1008
|
|
|
981
1009
|
* `<boolean>`
|
|
982
1010
|
|
|
983
|
-
|
|
984
|
-
In OpenGL mode, you
|
|
1011
|
+
Is `true` if the window was created in OpenGl mode.
|
|
1012
|
+
In OpenGL mode, you must use OpenGL calls to render to the window.
|
|
985
1013
|
Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-options) will fail.
|
|
986
1014
|
|
|
987
1015
|
### window.webgpu
|
|
988
1016
|
|
|
989
1017
|
* `<boolean>`
|
|
990
1018
|
|
|
991
|
-
|
|
992
|
-
In WebGPU mode, you
|
|
1019
|
+
Is `true` if the window was created in WebGPU mode.
|
|
1020
|
+
In WebGPU mode, you must use WebGPU calls to render to the window.
|
|
993
1021
|
Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-options) will fail.
|
|
994
1022
|
|
|
995
1023
|
### window.native
|
|
@@ -1000,14 +1028,15 @@ Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-options) wi
|
|
|
1000
1028
|
The native type of `handle` is HWND on Windows, NSView* on macOS, and Window (unsigned long) on Linux.
|
|
1001
1029
|
It should work exactly like the [`win.getNativeWindowHandle()`](https://www.electronjs.org/docs/latest/api/browser-window#wingetnativewindowhandle) electron method.
|
|
1002
1030
|
|
|
1003
|
-
|
|
1004
|
-
Please ignore these.
|
|
1031
|
+
The `window.native` object might also sometimes include extra fields other than the ones documented here.
|
|
1032
|
+
Please ignore and do not use these.
|
|
1033
|
+
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
1034
|
|
|
1006
1035
|
### window.maximized
|
|
1007
1036
|
|
|
1008
1037
|
* `<boolean>`
|
|
1009
1038
|
|
|
1010
|
-
|
|
1039
|
+
Is `true` if the window is maximized.
|
|
1011
1040
|
|
|
1012
1041
|
### window.maximize()
|
|
1013
1042
|
|
|
@@ -1017,7 +1046,7 @@ Maximizes the window.
|
|
|
1017
1046
|
|
|
1018
1047
|
* `<boolean>`
|
|
1019
1048
|
|
|
1020
|
-
|
|
1049
|
+
Is `true` if the window is minimized.
|
|
1021
1050
|
|
|
1022
1051
|
### window.minimize()
|
|
1023
1052
|
|
|
@@ -1025,13 +1054,13 @@ Minimizes the window.
|
|
|
1025
1054
|
|
|
1026
1055
|
### window.restore()
|
|
1027
1056
|
|
|
1028
|
-
Restores the window so it
|
|
1057
|
+
Restores the window so it is neither minimized nor maximized.
|
|
1029
1058
|
|
|
1030
1059
|
### window.focused
|
|
1031
1060
|
|
|
1032
1061
|
* `<boolean>`
|
|
1033
1062
|
|
|
1034
|
-
|
|
1063
|
+
Is `true` if the window has keyboard input.
|
|
1035
1064
|
|
|
1036
1065
|
### window.focus()
|
|
1037
1066
|
|
|
@@ -1041,39 +1070,39 @@ Gives the window the keyboard focus.
|
|
|
1041
1070
|
|
|
1042
1071
|
* `<boolean>`
|
|
1043
1072
|
|
|
1044
|
-
|
|
1073
|
+
Is `true` if the mouse is over the window.
|
|
1045
1074
|
|
|
1046
1075
|
### window.skipTaskbar
|
|
1047
1076
|
|
|
1048
1077
|
* `<boolean>`
|
|
1049
1078
|
|
|
1050
1079
|
X11 only.
|
|
1051
|
-
|
|
1052
|
-
Such a window
|
|
1080
|
+
Is `true` if the window was created with `skipTaskbar: true`.
|
|
1081
|
+
Such a window is not added to the taskbar.
|
|
1053
1082
|
|
|
1054
1083
|
### window.popupMenu
|
|
1055
1084
|
|
|
1056
1085
|
* `<boolean>`
|
|
1057
1086
|
|
|
1058
1087
|
X11 only.
|
|
1059
|
-
|
|
1060
|
-
Such a window
|
|
1088
|
+
Is `true` if the window was created with `popupMenu: true`.
|
|
1089
|
+
Such a window is always treated as a popup menu.
|
|
1061
1090
|
|
|
1062
1091
|
### window.tooltip
|
|
1063
1092
|
|
|
1064
1093
|
* `<boolean>`
|
|
1065
1094
|
|
|
1066
1095
|
X11 only.
|
|
1067
|
-
|
|
1068
|
-
Such a window
|
|
1096
|
+
Is `true` if the window was created with `tooltip: true`.
|
|
1097
|
+
Such a window is always treated as a tooltip.
|
|
1069
1098
|
|
|
1070
1099
|
### window.utility
|
|
1071
1100
|
|
|
1072
1101
|
* `<boolean>`
|
|
1073
1102
|
|
|
1074
1103
|
X11 only.
|
|
1075
|
-
|
|
1076
|
-
Such a window
|
|
1104
|
+
Is `true` if the window was created with `utility: true`.
|
|
1105
|
+
Such a window is always treated as a utility window.
|
|
1077
1106
|
|
|
1078
1107
|
### window.render(width, height, stride, format, buffer[, options])
|
|
1079
1108
|
|
|
@@ -1086,7 +1115,7 @@ Such a window will always be treated as a utility window.
|
|
|
1086
1115
|
Displays an image in the window.
|
|
1087
1116
|
|
|
1088
1117
|
By default the image is displayed over the entire surface of the window.
|
|
1089
|
-
You
|
|
1118
|
+
You may pass the optional `dstRect` parameter to set where exactly on the window to display the image.
|
|
1090
1119
|
The rest of the window will be filled with black.
|
|
1091
1120
|
|
|
1092
1121
|
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 +1128,7 @@ Possible values are:
|
|
|
1099
1128
|
| `'linear'` | `SDL_ScaleModeLinear` | linear filtering |
|
|
1100
1129
|
| `'best'` | `SDL_ScaleModeBest` | anisotropic filtering |
|
|
1101
1130
|
|
|
1102
|
-
If the window was created with either of the `opengl` or `webgpu` options, then you
|
|
1131
|
+
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
1132
|
Calls to `render()` will fail.
|
|
1104
1133
|
|
|
1105
1134
|
### window.setIcon(width, height, stride, format, buffer)
|
|
@@ -1113,7 +1142,7 @@ Set's the window's icon, usually displayed in the title bar and the taskbar.
|
|
|
1113
1142
|
* `untilFocused: <boolean>` Whether to keep flashing the window until the user focuses it. Default: `false`
|
|
1114
1143
|
|
|
1115
1144
|
Flash the window briefly to get attention.
|
|
1116
|
-
If `untilFocused` is set, the window will
|
|
1145
|
+
If `untilFocused` is set, the window will continue flashing until the user focuses it.
|
|
1117
1146
|
|
|
1118
1147
|
### window.stopFlashing()
|
|
1119
1148
|
|
|
@@ -1123,8 +1152,8 @@ Stop the window from flashing.
|
|
|
1123
1152
|
|
|
1124
1153
|
* `<boolean>`
|
|
1125
1154
|
|
|
1126
|
-
|
|
1127
|
-
A destroyed window object
|
|
1155
|
+
Is `true` if the window is destroyed.
|
|
1156
|
+
A destroyed window object must not be used any further.
|
|
1128
1157
|
|
|
1129
1158
|
### window.destroy()
|
|
1130
1159
|
|
|
@@ -1133,7 +1162,7 @@ Destroys the window.
|
|
|
1133
1162
|
### window.destroyGently()
|
|
1134
1163
|
|
|
1135
1164
|
Asks before destroying the window.
|
|
1136
|
-
The difference between this function and [destroy()](#windowdestroy) is that this function
|
|
1165
|
+
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
1166
|
|
|
1138
1167
|
|
|
1139
1168
|
## sdl.keyboard
|
|
@@ -1146,7 +1175,8 @@ If your application cares about the layout of the keyboard (for example using th
|
|
|
1146
1175
|
|
|
1147
1176
|
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
1177
|
|
|
1149
|
-
More commonly, you don't care about the physical key itself but about the "meaning" associated with each key:
|
|
1178
|
+
More commonly, you don't care about the physical key itself but about the "meaning" associated with each key:
|
|
1179
|
+
the character that it produces ("a", "b", "@", " ", .e.t.c.) or the function that it corresponds to ("Esc", "F4", "Ctrl", e.t.c.).
|
|
1150
1180
|
Your operating system provides a "keyboard mapping" that associates physical keys with their corresponding meaning.
|
|
1151
1181
|
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
1182
|
These meanings are represented as [virtual key strings](#virtual-keys).
|
|
@@ -1443,14 +1473,14 @@ Retuns `null` if the scancode does not currespond to a key in the current mappin
|
|
|
1443
1473
|
|
|
1444
1474
|
Maps a key to the corresponding scancode based on the current keyboard mapping.
|
|
1445
1475
|
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
|
|
1476
|
+
If multiple physical keys produce the same virtual key, then only the first one is returned.
|
|
1447
1477
|
|
|
1448
1478
|
### sdl.keyboard.getState()
|
|
1449
1479
|
|
|
1450
|
-
* Returns: `<boolean[]>` an
|
|
1480
|
+
* Returns: `<boolean[]>` an array representing the state of each key.
|
|
1451
1481
|
|
|
1452
1482
|
The returned array can be indexed with [`Scancode`](#enum-scancode) values.
|
|
1453
|
-
|
|
1483
|
+
Each value in the array is either `true` if the corresponding key is pressed, or `false` otherwise.
|
|
1454
1484
|
|
|
1455
1485
|
|
|
1456
1486
|
## sdl.mouse
|
|
@@ -1469,7 +1499,7 @@ A mouse can have many buttons, but the values for the three most common ones are
|
|
|
1469
1499
|
### sdl.mouse.getButton(button)
|
|
1470
1500
|
|
|
1471
1501
|
* `button: <number>` The index of the button.
|
|
1472
|
-
* Returns: `<boolean>`
|
|
1502
|
+
* Returns: `<boolean>` Is `true` if the button is pressed.
|
|
1473
1503
|
|
|
1474
1504
|
Queries the state of a single mouse button.
|
|
1475
1505
|
|
|
@@ -1526,13 +1556,13 @@ The hotspot represents the pixel that is considered to be under the mouse.
|
|
|
1526
1556
|
|
|
1527
1557
|
### sdl.mouse.showCursor([show])
|
|
1528
1558
|
|
|
1529
|
-
* `show: <boolean>` If `true` then the mouse cursor
|
|
1559
|
+
* `show: <boolean>` If `true` then the mouse cursor is made visible. Default: `true`
|
|
1530
1560
|
|
|
1531
1561
|
Changes the visibility of the mouse cursor.
|
|
1532
1562
|
|
|
1533
1563
|
### sdl.mouse.hideCursor()
|
|
1534
1564
|
|
|
1535
|
-
Equivalent to [`sdl.mouse.showCursor
|
|
1565
|
+
Equivalent to [`sdl.mouse.showCursor(false)`](#sdlmouseshowcursorshow).
|
|
1536
1566
|
|
|
1537
1567
|
### sdl.mouse.redrawCursor()
|
|
1538
1568
|
|
|
@@ -1540,7 +1570,7 @@ Forces a cursor redraw.
|
|
|
1540
1570
|
|
|
1541
1571
|
### sdl.mouse.capture([capture])
|
|
1542
1572
|
|
|
1543
|
-
* `capture: <boolean>` If `true` the mouse
|
|
1573
|
+
* `capture: <boolean>` If `true` the mouse is to be captured by the current window. Default: `true`
|
|
1544
1574
|
|
|
1545
1575
|
When the mouse has been captured you will continue receiving mouse events even if the mouse is not over a window.
|
|
1546
1576
|
|
|
@@ -1604,13 +1634,13 @@ When this event is emitted, all instances that were opened from the removed devi
|
|
|
1604
1634
|
* `<object>[]`
|
|
1605
1635
|
* `id: <number>` The unique id for the device.
|
|
1606
1636
|
* `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
|
|
1637
|
+
* `path: <string>|<null>` The implementation dependent path of the device, or `null` if it can't be determined.
|
|
1638
|
+
* `type: <JoystickType>|<null>` The type of the device, or `null` if it can't be determined.
|
|
1639
|
+
* `guid: <string>|<null>` The GUID of the device, or `null` if it can't be determined.
|
|
1640
|
+
* `vendor: <number>|<null>` The USB vendor ID of the device, or `null` if it can't be determined.
|
|
1641
|
+
* `product: <number>|<null>` The USB product ID of the device, or `null` if it can't be determined.
|
|
1642
|
+
* `version: <number>|<null>` The USB product version of the device, or `null` if it can't be determined.
|
|
1643
|
+
* `player: <number>|<null>` The player index for the device, or `null` if it can't be determined.
|
|
1614
1644
|
|
|
1615
1645
|
A list of all the detected joystick devices.
|
|
1616
1646
|
|
|
@@ -1648,15 +1678,15 @@ Sample output:
|
|
|
1648
1678
|
|
|
1649
1679
|
### sdl.joystick.openDevice(device)
|
|
1650
1680
|
|
|
1651
|
-
* `device: <object>` An object from [`sdl.joystick.devices`](#sdljoystickdevices) that
|
|
1681
|
+
* `device: <object>` An object from [`sdl.joystick.devices`](#sdljoystickdevices) that is to be opened.
|
|
1652
1682
|
* Returns: [`<joystickInstance>`](#class-joystickinstance) an object representing the opened joystick device instance.
|
|
1653
1683
|
|
|
1654
1684
|
Initializes a joystick device and returns a corresponding instance.
|
|
1655
1685
|
|
|
1656
|
-
## class
|
|
1686
|
+
## class joystickInstance
|
|
1657
1687
|
|
|
1658
|
-
|
|
1659
|
-
Instead, objects returned by [`sdl.joystick.openDevice()`](#sdljoystickopendevicedevice) are of
|
|
1688
|
+
The `JoystickInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
1689
|
+
Instead, objects returned by [`sdl.joystick.openDevice()`](#sdljoystickopendevicedevice) are of type `JoystickInstance`.
|
|
1660
1690
|
|
|
1661
1691
|
<a id="joystick-instance-event-axismotion"></a>
|
|
1662
1692
|
|
|
@@ -1709,19 +1739,19 @@ Handle cleanup here.
|
|
|
1709
1739
|
|
|
1710
1740
|
* `<object>`
|
|
1711
1741
|
|
|
1712
|
-
The [device](#sdljoystickdevices) from which
|
|
1742
|
+
The [device](#sdljoystickdevices) from which the instance was opened.
|
|
1713
1743
|
|
|
1714
1744
|
### joystickInstance.firmwareVersion
|
|
1715
1745
|
|
|
1716
1746
|
* `<number>|<null>`
|
|
1717
1747
|
|
|
1718
|
-
The joystick's firmware version, or `null` if it
|
|
1748
|
+
The joystick's firmware version, or `null` if it is not available.
|
|
1719
1749
|
|
|
1720
1750
|
### joystickInstance.serialNumber
|
|
1721
1751
|
|
|
1722
1752
|
* `<string>|<null>`
|
|
1723
1753
|
|
|
1724
|
-
The joystick's serial number, or `null` if it
|
|
1754
|
+
The joystick's serial number, or `null` if it is not available.
|
|
1725
1755
|
|
|
1726
1756
|
### joystickInstance.axes
|
|
1727
1757
|
|
|
@@ -1744,7 +1774,7 @@ An array of values, each corresponding to the position of one of the joystick's
|
|
|
1744
1774
|
* `<boolean>[]`
|
|
1745
1775
|
|
|
1746
1776
|
An array of values, each corresponding to the state of one of the joystick's buttons.
|
|
1747
|
-
|
|
1777
|
+
Each value in the object isarray is either `true` if the corresponding button is pressed, or `false` otherwise.
|
|
1748
1778
|
|
|
1749
1779
|
### joystickInstance.hats
|
|
1750
1780
|
|
|
@@ -1762,7 +1792,7 @@ The current power level of the joystick device, or `null` if it is unknown.
|
|
|
1762
1792
|
|
|
1763
1793
|
* `index: <number>` The player index to assign to the joystick.
|
|
1764
1794
|
|
|
1765
|
-
Sets the player index of
|
|
1795
|
+
Sets the player index of the joystick.
|
|
1766
1796
|
|
|
1767
1797
|
### joystickInstance.resetPlayer()
|
|
1768
1798
|
|
|
@@ -1772,7 +1802,7 @@ Clears player assignment and player led.
|
|
|
1772
1802
|
|
|
1773
1803
|
* `<boolean>`
|
|
1774
1804
|
|
|
1775
|
-
|
|
1805
|
+
Is `true` if the joystick has a LED light whose color can be controlled.
|
|
1776
1806
|
|
|
1777
1807
|
### joystickInstance.setLed(red, green, blue)
|
|
1778
1808
|
|
|
@@ -1786,9 +1816,9 @@ Sets the color of the LED light on the joystick.
|
|
|
1786
1816
|
|
|
1787
1817
|
* `<boolean>`
|
|
1788
1818
|
|
|
1789
|
-
|
|
1819
|
+
Is `true` if the joystick has rumble motors.
|
|
1790
1820
|
|
|
1791
|
-
### joystickInstance.rumble([low, [
|
|
1821
|
+
### joystickInstance.rumble([low[, high[, duration]]])
|
|
1792
1822
|
|
|
1793
1823
|
* `low: <number>` The intensity of the low frequency rumble motor, from `0` to `1`. Default: `1`
|
|
1794
1824
|
* `high: <number>` The intensity of the high frequency rumble motor, from `0` to `1`. Default: `1`
|
|
@@ -1800,15 +1830,15 @@ Calling this function again before `duration` has ran out, overrides the previou
|
|
|
1800
1830
|
### joystickInstance.stopRumble()
|
|
1801
1831
|
|
|
1802
1832
|
Stops the joystick rumbling.
|
|
1803
|
-
Equivalent to `joystickInstance.rumble(0, 0)
|
|
1833
|
+
Equivalent to [`joystickInstance.rumble(0, 0)`](#joystickinstancerumblelow-high-duration).
|
|
1804
1834
|
|
|
1805
1835
|
### joystickInstance.hasRumbleTriggers
|
|
1806
1836
|
|
|
1807
1837
|
* `<boolean>`
|
|
1808
1838
|
|
|
1809
|
-
|
|
1839
|
+
Is `true` if the joystick has rumble motors on the triggers.
|
|
1810
1840
|
|
|
1811
|
-
### joystickInstance.rumbleTriggers([left, [
|
|
1841
|
+
### joystickInstance.rumbleTriggers([left[, right[, duration]]])
|
|
1812
1842
|
|
|
1813
1843
|
* `left: <number>` The intensity of the left trigger rumble motor, from `0` to `1`. Default: `1`
|
|
1814
1844
|
* `right: <number>` The intensity of the right trigger rumble motor, from `0` to `1`. Default: `1`
|
|
@@ -1820,14 +1850,14 @@ Calling this function again before `duration` has ran out, overrides the previou
|
|
|
1820
1850
|
### joystickInstance.stopRumbleTriggers()
|
|
1821
1851
|
|
|
1822
1852
|
Stops the joystick trigger rumbling.
|
|
1823
|
-
Equivalent to `joystickInstance.rumbleTriggers(0, 0)
|
|
1853
|
+
Equivalent to [`joystickInstance.rumbleTriggers(0, 0)`](#joystickinstancerumbletriggersleft-right-duration).
|
|
1824
1854
|
|
|
1825
1855
|
### joystickInstance.closed
|
|
1826
1856
|
|
|
1827
1857
|
* `<boolean>`
|
|
1828
1858
|
|
|
1829
|
-
|
|
1830
|
-
A closed instance object
|
|
1859
|
+
Is `true` if the instance is closed.
|
|
1860
|
+
A closed instance object must not be used any further.
|
|
1831
1861
|
|
|
1832
1862
|
### joystickInstance.close()
|
|
1833
1863
|
|
|
@@ -1843,10 +1873,10 @@ With a pure joystick instance it's impossible to know which axis or button corre
|
|
|
1843
1873
|
|
|
1844
1874
|
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
1875
|
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,
|
|
1876
|
+
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
1877
|
See the sample output [`here`](#sdlcontrollerdevices) for an example.
|
|
1848
1878
|
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
|
-
|
|
1879
|
+
Add them via:
|
|
1850
1880
|
|
|
1851
1881
|
```js
|
|
1852
1882
|
const url = 'https://raw.githubusercontent.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt'
|
|
@@ -1880,21 +1910,21 @@ When this event is emitted, all instances that were opened from the removed devi
|
|
|
1880
1910
|
* `mappings: <string>[]` An array of mappings to register.
|
|
1881
1911
|
|
|
1882
1912
|
Registers new mappings for controllers.
|
|
1883
|
-
This
|
|
1913
|
+
This may cause already opened controller instances to be [remapped](#event-remap).
|
|
1884
1914
|
|
|
1885
1915
|
### sdl.controller.devices
|
|
1886
1916
|
|
|
1887
1917
|
* `<object>[]`
|
|
1888
1918
|
* `id: <number>` The unique id for the device.
|
|
1889
1919
|
* `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
|
|
1920
|
+
* `path: <string>|<null>` The implementation dependent path of the device, or `null` if it can't be determined.
|
|
1921
|
+
* `type: <string>|<null>` The type of the device, or `null` if it can't be determined.
|
|
1922
|
+
* `guid: <string>|<null>` The GUID of the device, or `null` if it can't be determined.
|
|
1923
|
+
* `vendor: <number>|<null>` The USB vendor ID of the device, or `null` if it can't be determined.
|
|
1924
|
+
* `product: <number>|<null>` The USB product ID of the device, or `null` if it can't be determined.
|
|
1925
|
+
* `version: <number>|<null>` The USB product version of the device, or `null` if it can't be determined.
|
|
1926
|
+
* `player: <number>|<null>` The player index for the device, or `null` if it can't be determined.
|
|
1927
|
+
* `mapping: <string>|<null>` The axis and button mapping for the device, or `null` if it can't be determined.
|
|
1898
1928
|
|
|
1899
1929
|
A list of all the detected controller devices.
|
|
1900
1930
|
|
|
@@ -1937,15 +1967,15 @@ Sample output:
|
|
|
1937
1967
|
|
|
1938
1968
|
### sdl.controller.openDevice(device)
|
|
1939
1969
|
|
|
1940
|
-
* `device: <object>` An object from [`sdl.controller.devices`](#sdlcontrollerdevices) that
|
|
1970
|
+
* `device: <object>` An object from [`sdl.controller.devices`](#sdlcontrollerdevices) that is to be opened.
|
|
1941
1971
|
* Returns: [`<ControllerInstance>`](#class-controllerinstance) an object representing the opened controller device instance.
|
|
1942
1972
|
|
|
1943
1973
|
Initializes an controller device and returns a corresponding instance.
|
|
1944
1974
|
|
|
1945
1975
|
## class ControllerInstance
|
|
1946
1976
|
|
|
1947
|
-
|
|
1948
|
-
Instead, objects returned by [`sdl.controller.openDevice()`](#sdlcontrolleropendevicedevice) are of
|
|
1977
|
+
The `ControllerInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
1978
|
+
Instead, objects returned by [`sdl.controller.openDevice()`](#sdlcontrolleropendevicedevice) are of type `ControllerInstance`.
|
|
1949
1979
|
|
|
1950
1980
|
<a id="controller-instance-event-axismotion"></a>
|
|
1951
1981
|
|
|
@@ -1974,8 +2004,8 @@ Fired when one of the controller's buttons is released.
|
|
|
1974
2004
|
|
|
1975
2005
|
### Event: 'remap'
|
|
1976
2006
|
|
|
1977
|
-
Fired when a new mapping for
|
|
1978
|
-
This
|
|
2007
|
+
Fired when a new mapping for the controller is applied (usually via [`sdl.controller.addMappings()`](#sdlcontrolleraddmappingsmappings)).
|
|
2008
|
+
This may cause all of the controller's axes and buttons to aquire new values.
|
|
1979
2009
|
|
|
1980
2010
|
<a id="controller-instance-event-close"></a>
|
|
1981
2011
|
|
|
@@ -1988,7 +2018,7 @@ Handle cleanup here.
|
|
|
1988
2018
|
|
|
1989
2019
|
* `<object>`
|
|
1990
2020
|
|
|
1991
|
-
The [device](#sdlcontrollerdevices) from which
|
|
2021
|
+
The [device](#sdlcontrollerdevices) from which the instance was opened.
|
|
1992
2022
|
|
|
1993
2023
|
### controllerInstance.firmwareVersion
|
|
1994
2024
|
|
|
@@ -2000,14 +2030,14 @@ The controller's firmware version.
|
|
|
2000
2030
|
|
|
2001
2031
|
* `<string>|<null>`
|
|
2002
2032
|
|
|
2003
|
-
The controller's serial number, or `null` if it
|
|
2033
|
+
The controller's serial number, or `null` if it is not available.
|
|
2004
2034
|
|
|
2005
2035
|
### controllerInstance.steamHandle
|
|
2006
2036
|
|
|
2007
2037
|
* `<Buffer>|<null>`
|
|
2008
2038
|
|
|
2009
|
-
The controller's steam handle, or `null` if it
|
|
2010
|
-
The `Buffer`
|
|
2039
|
+
The controller's steam handle, or `null` if it is not available.
|
|
2040
|
+
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
2041
|
|
|
2012
2042
|
### controllerInstance.axes
|
|
2013
2043
|
|
|
@@ -2047,7 +2077,7 @@ It may be necessary to impose certain tolerances on these values to account for
|
|
|
2047
2077
|
* `paddle4: <boolean>` Paddle 4 pressed
|
|
2048
2078
|
|
|
2049
2079
|
An object mapping each of the controller's buttons to a boolean value.
|
|
2050
|
-
|
|
2080
|
+
Each value in the object is either `true` if the corresponding button is pressed, or `false` otherwise.
|
|
2051
2081
|
|
|
2052
2082
|
### controllerInstance.power
|
|
2053
2083
|
|
|
@@ -2059,7 +2089,7 @@ The current power level of the joystick device, or `null` if it is unknown.
|
|
|
2059
2089
|
|
|
2060
2090
|
* `index: <number>` The player index to assign to the controller.
|
|
2061
2091
|
|
|
2062
|
-
Sets the player index of
|
|
2092
|
+
Sets the player index of the controller.
|
|
2063
2093
|
|
|
2064
2094
|
### controllerInstance.resetPlayer()
|
|
2065
2095
|
|
|
@@ -2069,7 +2099,7 @@ Clears player assignment and player led.
|
|
|
2069
2099
|
|
|
2070
2100
|
* `<boolean>`
|
|
2071
2101
|
|
|
2072
|
-
|
|
2102
|
+
Is `true` if the controller has a LED light whose color can be controlled.
|
|
2073
2103
|
|
|
2074
2104
|
### controllerInstance.setLed(red, green, blue)
|
|
2075
2105
|
|
|
@@ -2083,9 +2113,9 @@ Sets the color of the LED light on the controller.
|
|
|
2083
2113
|
|
|
2084
2114
|
* `<boolean>`
|
|
2085
2115
|
|
|
2086
|
-
|
|
2116
|
+
Is `true` if the controller has rumble motors.
|
|
2087
2117
|
|
|
2088
|
-
### controllerInstance.rumble([low, [
|
|
2118
|
+
### controllerInstance.rumble([low[, high[, duration]]])
|
|
2089
2119
|
|
|
2090
2120
|
* `low: <number>` The intensity of the low frequency rumble motor, from `0` to `1`. Default: `1`
|
|
2091
2121
|
* `high: <number>` The intensity of the high frequency rumble motor, from `0` to `1`. Default: `1`
|
|
@@ -2097,15 +2127,15 @@ Calling this function again before `duration` has ran out, overrides the previou
|
|
|
2097
2127
|
### controllerInstance.stopRumble()
|
|
2098
2128
|
|
|
2099
2129
|
Stops the controller rumbling.
|
|
2100
|
-
Equivalent to `controllerInstance.rumble(0, 0)
|
|
2130
|
+
Equivalent to [`controllerInstance.rumble(0, 0)`](#controllerinstancerumblelow-high-duration).
|
|
2101
2131
|
|
|
2102
2132
|
### controllerInstance.hasRumbleTriggers
|
|
2103
2133
|
|
|
2104
2134
|
* `<boolean>`
|
|
2105
2135
|
|
|
2106
|
-
|
|
2136
|
+
Is `true` if the controller has rumble motors on the triggers.
|
|
2107
2137
|
|
|
2108
|
-
### controllerInstance.rumbleTriggers([left, [
|
|
2138
|
+
### controllerInstance.rumbleTriggers([left[, right[, duration]]])
|
|
2109
2139
|
|
|
2110
2140
|
* `left: <number>` The intensity of the left trigger rumble motor, from `0` to `1`. Default: `1`
|
|
2111
2141
|
* `right: <number>` The intensity of the right trigger rumble motor, from `0` to `1`. Default: `1`
|
|
@@ -2117,14 +2147,14 @@ Calling this function again before `duration` has ran out, overrides the previou
|
|
|
2117
2147
|
### controllerInstance.stopRumbleTriggers()
|
|
2118
2148
|
|
|
2119
2149
|
Stops the controller trigger rumbling.
|
|
2120
|
-
Equivalent to `controllerInstance.rumbleTriggers(0, 0)
|
|
2150
|
+
Equivalent to [`controllerInstance.rumbleTriggers(0, 0)`](#controllerinstancerumbletriggersleft-right-duration).
|
|
2121
2151
|
|
|
2122
2152
|
### controllerInstance.closed
|
|
2123
2153
|
|
|
2124
2154
|
* `<boolean>`
|
|
2125
2155
|
|
|
2126
|
-
|
|
2127
|
-
A closed instance object
|
|
2156
|
+
Is `true` if the instance is closed.
|
|
2157
|
+
A closed instance object must not be used any further.
|
|
2128
2158
|
|
|
2129
2159
|
### controllerInstance.close()
|
|
2130
2160
|
|
|
@@ -2137,33 +2167,38 @@ Closes the instance.
|
|
|
2137
2167
|
|
|
2138
2168
|
* `<number>`
|
|
2139
2169
|
|
|
2140
|
-
|
|
2141
|
-
|
|
2170
|
+
Accelerometers are affected by the force of gravity:
|
|
2171
|
+
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.
|
|
2172
|
+
Use the `sdl.sensor.STANDARD_GRAVITY` constant to correct for gravitational acceleration if your application requires it.
|
|
2142
2173
|
|
|
2143
2174
|
### sdl.sensor.devices
|
|
2144
2175
|
|
|
2145
2176
|
* `<object>[]`
|
|
2146
2177
|
* `id: <number>` The unique id of the device.
|
|
2147
2178
|
* `name: <string>` The name of the device.
|
|
2148
|
-
* `type: <string>|<null>` Either `'accelerometer'
|
|
2149
|
-
* `side: <string>|<null>`
|
|
2179
|
+
* `type: <string>|<null>` Either `'accelerometer'` or `'gyroscope'`. Is `null` if it can't be determined.
|
|
2180
|
+
* `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
2181
|
|
|
2151
2182
|
A list of all the detected sensor devices.
|
|
2183
|
+
|
|
2184
|
+
Some sensors have a `side`, sucha as those on the Joy-Con controller.
|
|
2185
|
+
For most other sensors `side` is `null`.
|
|
2186
|
+
|
|
2152
2187
|
Sample output:
|
|
2153
2188
|
|
|
2154
2189
|
// TODO
|
|
2155
2190
|
|
|
2156
2191
|
### sdl.sensor.openDevice(device)
|
|
2157
2192
|
|
|
2158
|
-
* `device: <object>` An object from [`sdl.sensor.devices`](#sdlsensordevices) that
|
|
2193
|
+
* `device: <object>` An object from [`sdl.sensor.devices`](#sdlsensordevices) that is to be opened.
|
|
2159
2194
|
* Returns: [`<SensorInstance>`](#class-sensorinstance) an object representing the opened sensor device instance.
|
|
2160
2195
|
|
|
2161
2196
|
Initializes a sensor device and returns a corresponding instance.
|
|
2162
2197
|
|
|
2163
2198
|
## class SensorInstance
|
|
2164
2199
|
|
|
2165
|
-
|
|
2166
|
-
Instead, objects returned by [`sdl.sensor.openDevice()`](#sdlsensoropendevicedevice) are of
|
|
2200
|
+
The `SensorInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
2201
|
+
Instead, objects returned by [`sdl.sensor.openDevice()`](#sdlsensoropendevicedevice) are of type `SensorInstance`.
|
|
2167
2202
|
|
|
2168
2203
|
<a id="sensor-instance-event-update"></a>
|
|
2169
2204
|
|
|
@@ -2183,24 +2218,24 @@ Handle cleanup here.
|
|
|
2183
2218
|
|
|
2184
2219
|
* `<object>`
|
|
2185
2220
|
|
|
2186
|
-
The [device](#sdlsensordevices) from which
|
|
2221
|
+
The [device](#sdlsensordevices) from which the `sensorInstance` was opened.
|
|
2187
2222
|
|
|
2188
2223
|
### sensorInstance.data
|
|
2189
2224
|
|
|
2190
2225
|
* `<object>`
|
|
2191
|
-
* `timestamp: <number>|<null>` The time
|
|
2226
|
+
* `timestamp: <number>|<null>` The time the latest measurement was taken __in microseconds__, or `null` if it can't be determined.
|
|
2192
2227
|
* `x: <number>` X axis value.
|
|
2193
2228
|
* `y: <number>` Y axis value.
|
|
2194
2229
|
* `z: <number>` Z axis value.
|
|
2195
2230
|
|
|
2196
2231
|
An object reporting the latest measurement from the sensor.
|
|
2197
2232
|
|
|
2198
|
-
For accelerometers, the values correspond to the current acceleration in meters per second squared.
|
|
2199
|
-
|
|
2233
|
+
For accelerometers, the `x`, `y`, and `z` values correspond to the current acceleration in meters per second squared.
|
|
2234
|
+
Keep in mind the accelerometers are affected by the force of gravity:
|
|
2235
|
+
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
2236
|
|
|
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.
|
|
2237
|
+
For gyroscopes, the `x`, `y`, and `z` values correspond to the current rate of rotation in radians per second.
|
|
2238
|
+
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
2239
|
|
|
2205
2240
|
For phones held in portrait mode and game controllers held in front of you, the axes are defined as follows:
|
|
2206
2241
|
* -X ... +X : left ... right
|
|
@@ -2211,8 +2246,8 @@ For phones held in portrait mode and game controllers held in front of you, the
|
|
|
2211
2246
|
|
|
2212
2247
|
* `<boolean>`
|
|
2213
2248
|
|
|
2214
|
-
|
|
2215
|
-
A closed instance object
|
|
2249
|
+
Is `true` if the instance is closed.
|
|
2250
|
+
A closed instance object must not be used any further.
|
|
2216
2251
|
|
|
2217
2252
|
### sensorInstance.close()
|
|
2218
2253
|
|
|
@@ -2232,7 +2267,7 @@ For audio with multiple channels, each point in time is represented by multiple
|
|
|
2232
2267
|
The samples in a frame are arranged as follows:
|
|
2233
2268
|
|
|
2234
2269
|
* For 1 channel (mono) a frame contains just the one sample.
|
|
2235
|
-
* For 2 channels (stereo) the frame
|
|
2270
|
+
* 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
2271
|
* For 4 channels (quad) the layout is front-left, front-right, rear-left, rear-right.
|
|
2237
2272
|
* For 6 channels (5.1) the layout is front-left, front-right, center, low-freq, rear-left, rear-right.
|
|
2238
2273
|
|
|
@@ -2319,7 +2354,7 @@ Check [`sdl.audio.devices`](#sdlaudiodevices) to get the new list of audio devic
|
|
|
2319
2354
|
|
|
2320
2355
|
Fired when an existing audio device is removed.
|
|
2321
2356
|
Check [`sdl.audio.devices`](#sdlaudiodevices) to get the new list of audio devices.
|
|
2322
|
-
When
|
|
2357
|
+
When the `'deviceRemove'` event is emitted, all instances that were opened from the removed device are closed automatically.
|
|
2323
2358
|
|
|
2324
2359
|
### sdl.audio.bytesPerSample(format)
|
|
2325
2360
|
|
|
@@ -2385,7 +2420,7 @@ This function is also available from `@kmamal/sdl/helpers`.
|
|
|
2385
2420
|
### sdl.audio.devices
|
|
2386
2421
|
|
|
2387
2422
|
* `<object>[]`
|
|
2388
|
-
* `type: <string>`
|
|
2423
|
+
* `type: <string>` Either `'playback'` or `'recording'`.
|
|
2389
2424
|
* `name: <string>` The name of the device.
|
|
2390
2425
|
|
|
2391
2426
|
A list of all the detected audio devices.
|
|
@@ -2398,8 +2433,8 @@ Sample output for PulseAudio:
|
|
|
2398
2433
|
]
|
|
2399
2434
|
```
|
|
2400
2435
|
|
|
2401
|
-
Note that
|
|
2402
|
-
Despite that, in many common cases, it
|
|
2436
|
+
Note that `sdl.audio.devices` may sometimes be an empty list.
|
|
2437
|
+
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
2438
|
|
|
2404
2439
|
```js
|
|
2405
2440
|
const playbackInstance = sdl.audio.openDevice({ type: 'playback' })
|
|
@@ -2408,39 +2443,45 @@ const playbackInstance = sdl.audio.openDevice({ type: 'playback' })
|
|
|
2408
2443
|
### sdl.audio.openDevice(device[, options])
|
|
2409
2444
|
|
|
2410
2445
|
* `device: <object>` An object from [`sdl.audio.devices`](#sdlaudiodevices), or a custom device.
|
|
2411
|
-
* `type: <string>`:
|
|
2446
|
+
* `type: <string>`: Either `'playback'` or `'recording'`.
|
|
2412
2447
|
* `name: <string>|<null>`: The name of the device. Optional.
|
|
2413
2448
|
* `options: <object>`
|
|
2414
2449
|
* `channels: <number>`: Number of audio channels. Valid values: `1`, `2`, `4`, `6`. Default: `1`
|
|
2415
2450
|
* `frequency: <number>`: The sampling frequency in frames per second. Default: `48e3`
|
|
2416
2451
|
* `format: `[`<SampleFormat>`](#sample-formats): The binary format for each sample. Default: `'f32'`
|
|
2417
|
-
* `buffered: <number>`: Number of frames
|
|
2452
|
+
* `buffered: <number>`: Number of frames buffered by the driver. Must be a power of `2`. Default: `4096`
|
|
2418
2453
|
* Returns: [`<AudioInstance>`](#class-audioinstance) an object representing the opened audio device instance.
|
|
2419
2454
|
|
|
2420
2455
|
Initializes an audio device for playback/recording and returns a corresponding instance.
|
|
2421
|
-
If the opened device is a playback device, then
|
|
2456
|
+
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).
|
|
2457
|
+
|
|
2458
|
+
Most of the time, you will be passing objects from [`sdl.audio.devices`](#sdlaudiodevices) for the `device` argument:
|
|
2459
|
+
|
|
2460
|
+
```js
|
|
2461
|
+
const device = sdl.audio.devices[selectedIndex]
|
|
2462
|
+
const playbackInstance = sdl.audio.openDevice(device)
|
|
2463
|
+
```
|
|
2422
2464
|
|
|
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:
|
|
2465
|
+
It's also possible to let SDL pick the most appropriate device by only passing the `type` property:
|
|
2425
2466
|
|
|
2426
2467
|
```js
|
|
2427
2468
|
const playbackInstance = sdl.audio.openDevice({ type: 'playback' })
|
|
2428
2469
|
```
|
|
2429
2470
|
|
|
2430
2471
|
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
|
|
2472
|
+
These drivers usually return an empty list for [`sdl.audio.devices`](#sdlaudiodevices).
|
|
2432
2473
|
|
|
2433
|
-
The `channels`, `frequency` and `format` options together define
|
|
2474
|
+
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
2475
|
See also the section on [audio data](#audio-data).
|
|
2435
2476
|
|
|
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
|
|
2477
|
+
The `buffered` option specifies the "delay" between the application and the audio driver.
|
|
2478
|
+
With smaller values you have smaller delays, but you also have to read/write data from/to the driver more frequently.
|
|
2479
|
+
Applications such as virtual instruments that need to play audio in reaction to user input should set `buffered` to a lower value.
|
|
2439
2480
|
|
|
2440
2481
|
|
|
2441
2482
|
## class AudioInstance
|
|
2442
2483
|
|
|
2443
|
-
|
|
2484
|
+
The `AudioInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
2444
2485
|
It only serves as the base class for [`AudioPlaybackInstance`](#class-audioplaybackinstance-extends-audioinstance) and [`AudioRecordingInstance`](#class-audiorecordinginstance-extends-audioinstance).
|
|
2445
2486
|
|
|
2446
2487
|
<a id="audio-instance-event-close"></a>
|
|
@@ -2460,7 +2501,7 @@ A unique identifier for the instance.
|
|
|
2460
2501
|
|
|
2461
2502
|
* `<object>`
|
|
2462
2503
|
|
|
2463
|
-
The device passed to [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) when
|
|
2504
|
+
The device passed to [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) when the `audioInstance` was opened.
|
|
2464
2505
|
|
|
2465
2506
|
### audioInstance.channels
|
|
2466
2507
|
|
|
@@ -2533,7 +2574,7 @@ The buffer size (in frames) the instance was opened with.
|
|
|
2533
2574
|
|
|
2534
2575
|
* `<boolean>`
|
|
2535
2576
|
|
|
2536
|
-
|
|
2577
|
+
Is `true` if the instance is currently playing.
|
|
2537
2578
|
|
|
2538
2579
|
### audioInstance.play([play])
|
|
2539
2580
|
|
|
@@ -2549,7 +2590,7 @@ Equivalent to [`audioInstance.play(false)`](#audioinstanceplayplay)
|
|
|
2549
2590
|
|
|
2550
2591
|
* `<number>`
|
|
2551
2592
|
|
|
2552
|
-
The number of bytes that are currently queued up, waiting to be either played by the
|
|
2593
|
+
The number of bytes that are currently queued up, waiting to be either played by the system or dequeued by the user.
|
|
2553
2594
|
|
|
2554
2595
|
### audioInstance.clearQueue()
|
|
2555
2596
|
|
|
@@ -2559,8 +2600,8 @@ Clears the queued data.
|
|
|
2559
2600
|
|
|
2560
2601
|
* `<boolean>`
|
|
2561
2602
|
|
|
2562
|
-
|
|
2563
|
-
A closed instance object
|
|
2603
|
+
Is `true` if the instance is closed.
|
|
2604
|
+
A closed instance object must not be used any further.
|
|
2564
2605
|
|
|
2565
2606
|
### audioInstance.close()
|
|
2566
2607
|
|
|
@@ -2569,21 +2610,21 @@ Closes the instance.
|
|
|
2569
2610
|
|
|
2570
2611
|
## class AudioPlaybackInstance extends AudioInstance
|
|
2571
2612
|
|
|
2572
|
-
|
|
2573
|
-
Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) are of
|
|
2613
|
+
The `AudioPlaybackInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
2614
|
+
Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) are of type `AudioPlaybackInstance`, if a playback device is opened.
|
|
2574
2615
|
|
|
2575
2616
|
### playbackInstance.enqueue(buffer[, bytes])
|
|
2576
2617
|
|
|
2577
2618
|
* `buffer: <Buffer>` The buffer to read data from.
|
|
2578
2619
|
* `bytes: <number>` The number of bytes to read from the buffer. Default: `buffer.length`
|
|
2579
2620
|
|
|
2580
|
-
Takes
|
|
2621
|
+
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
2622
|
|
|
2582
2623
|
|
|
2583
2624
|
## class AudioRecordingInstance extends AudioInstance
|
|
2584
2625
|
|
|
2585
|
-
|
|
2586
|
-
Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) are of
|
|
2626
|
+
The `AudioRecordingInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
|
|
2627
|
+
Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) are of type `AudioRecordingInstance`, if a recording device is opened.
|
|
2587
2628
|
|
|
2588
2629
|
### recordingInstance.dequeue(buffer[, bytes])
|
|
2589
2630
|
|
|
@@ -2591,7 +2632,7 @@ Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevic
|
|
|
2591
2632
|
* `bytes: <number>` The number of bytes to write to the buffer. Default: `buffer.length`
|
|
2592
2633
|
* Returns: `<number>` The actual number of bytes read.
|
|
2593
2634
|
|
|
2594
|
-
Takes recorded audio data that has
|
|
2635
|
+
Takes recorded audio data that has is waiting on the queue, and writes it to the provided buffer.
|
|
2595
2636
|
|
|
2596
2637
|
|
|
2597
2638
|
## sdl.clipboard
|
|
@@ -2621,23 +2662,27 @@ Changes the text contents of the clipboard.
|
|
|
2621
2662
|
### sdl.power.info
|
|
2622
2663
|
|
|
2623
2664
|
* `<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
|
|
2665
|
+
* `state: <string>|<null>` One of `'noBattery'`, `'battery'`, `'charging'`, `'charged'`. Is `null` if it can't be determinded.
|
|
2666
|
+
* `seconds: <number>|<null>` Seconds of battery life left, or `null` if not running on battery or if it can't be determinded.
|
|
2667
|
+
* `percent: <number>|<null>` Percentage of battery life left, or `null` if not running on battery or if it can't be determinded.
|
|
2627
2668
|
|
|
2628
2669
|
The curent power information of the device.
|
|
2629
2670
|
|
|
2630
2671
|
|
|
2631
2672
|
## Helpers
|
|
2632
2673
|
|
|
2633
|
-
The `@kmamal/sdl` library
|
|
2674
|
+
The `@kmamal/sdl` library must only be imported from the main thread.
|
|
2634
2675
|
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
|
|
2676
|
+
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
2677
|
|
|
2637
2678
|
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!
|
|
2679
|
+
This is still possible!
|
|
2680
|
+
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.
|
|
2681
|
+
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
2682
|
|
|
2640
|
-
Since these are just helpers and don't call any SLD code underneath it's safe to use them.
|
|
2683
|
+
Since these are just helpers and don't call any SLD code underneath it's safe to use them.
|
|
2684
|
+
They are made available through the `@kmamal/sdl/helpers` sub-module that does not load any of the native code.
|
|
2685
|
+
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
2686
|
|
|
2642
2687
|
The functions included in `@kmamal/sdl/helpers` are:
|
|
2643
2688
|
|
|
@@ -2651,18 +2696,18 @@ The functions included in `@kmamal/sdl/helpers` are:
|
|
|
2651
2696
|
|
|
2652
2697
|
## Building from source
|
|
2653
2698
|
|
|
2654
|
-
If
|
|
2699
|
+
If prebuilt binaries are not available for your platform, `@kmamal/sdl` tries to compile itself during installation.
|
|
2655
2700
|
A few prerequisites are necessary for that to work:
|
|
2656
2701
|
|
|
2657
|
-
First,
|
|
2702
|
+
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
2703
|
|
|
2659
|
-
On Mac, you
|
|
2660
|
-
|
|
2704
|
+
On Mac, you also need to install `xquartz` so that SDL can find the X11 headers it needs.
|
|
2705
|
+
The command to install `quartz` via homebrew is `brew install xquartz`.
|
|
2661
2706
|
|
|
2662
2707
|
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
|
|
2708
|
+
These are downloaded automatically through the [@kmamal/build-sdl](https://github.com/kmamal/build-sdl) package.
|
|
2709
|
+
If `@kmamal/build-sdl` has no prebuilt library for your platform, it tries to compile one on the spot.
|
|
2710
|
+
You need to have `cmake` installed for that to work.
|
|
2666
2711
|
|
|
2667
2712
|
---
|
|
2668
2713
|
|