@kmamal/sdl 0.11.7 → 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/README.md CHANGED
@@ -4,32 +4,41 @@
4
4
  [![Dependencies](https://img.shields.io/librariesio/release/npm/@kmamal/sdl)](https://libraries.io/npm/@kmamal%2Fsdl)
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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
- It should work on Linux, Mac, and Windows.
11
- Prebuilt binaries are available for x64 architectures, arm-based Macs, and Raspberry Pi.
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
- #### Canvas2D, WebGL, and WebGPU
20
+ Also allows using Canvas2D, WebGL, and WebGPU without a browser:
14
21
 
15
- One goal of this project is to allow using Canvas2D, WebGL, and WebGPU without a browser.
16
- You can use the [@napi-rs/canvas](https://www.npmjs.com/package/@napi-rs/canvas) package to render using the Canvas2D API.
17
- For WebGL you can use [@kmamal/gl](https://github.com/kmamal/headless-gl#readme) and for WebGPU you can use [@kmamal/gpu](https://github.com/kmamal/gpu#readme).
18
- Both WebGL and WebGPU support rendering directly to the window (without any intermediate buffer copying).
19
- Canvas2D still uses an intermediate buffer, but that might change in the future.
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
- SDL is bundled along with the binaries so a separate installation is not necessary.
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
- (But if things go wrong do look over [here](#building-from-source))
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
@@ -211,7 +220,7 @@ Check the [`examples/`](https://github.com/kmamal/node-sdl/tree/master/examples#
211
220
  * [window.utility](#windowutility)
212
221
  * [window.render(width, height, stride, format, buffer[, options])](#windowrenderwidth-height-stride-format-buffer-options)
213
222
  * [window.setIcon(width, height, stride, format, buffer)](#windowseticonwidth-height-stride-format-buffer)
214
- * [window.flash(untilFocused)](#windowflashuntilfocused)
223
+ * [window.flash([untilFocused])](#windowflashuntilfocused)
215
224
  * [window.stopFlashing()](#windowstopflashing)
216
225
  * [window.destroyed](#windowdestroyed)
217
226
  * [window.destroy()](#windowdestroy)
@@ -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 SDL version the bindings were compiled against.
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 SDL version of the dynamic library the is loaded.
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
- This object is filled with the information produced during the initialization of SDL.
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).
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 can be `null`.
383
- This can happen on systems that don't have any compatible devices, such as on a CI pipeline.
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 will need to provide an image to the library:
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. This is usually equal to `width * bytesPerPixel`, but can be larger if the rows of the buffer are padded to always be some multiple of bytes.
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 that their `width` and `height` would indicate.
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 have to correspond to pixels.
451
- If you need to know a window's width and height in pixels, you should use the `pixelWidth` and `pixelHeight` properties.
452
- You should be doing this always, since you don't know beforehand if your program will be running on a high-dpi system.
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>` Will appear in the window's title bar. Default: `''`
599
- * `display: <number>` An object from `sdl.video.displays` to specify in which display the window will appear (if you have multiple displays). Default: `sdl.video.displays[0]`
600
- * `x: <number>` The x position in which the window will appear relative to the screen, or `null` for centered. Default: `null`
601
- * `y: <number>` The y position in which the window will appear relative to the screen, or `null` for centered. Default: `null`
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 this window above others. Default: `false`
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 this window to the taskbar. Default: `false`
614
- * `popupMenu: <boolean>` X11 only. Set to `true` to treat this window like a popup menu. Default: `false`
615
- * `tooltip: <boolean>` X11 only. Set to `true` to treat this window like a tooltip. Default: `false`
616
- * `utility: <boolean>` X11 only. Set to `true` to treat this window like a utility window. Default: `false`
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
- * If you specify the `display` option, you can't also specify the `x` or `y` options, and vice-versa.
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 can only render to the window with OpenGL/WebGPU calls.
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
- This class is not directly exposed by the API so you can't use it with the `new` operator.
635
- Instead, objects returned by [`sdl.video.createWindow()`](#sdlvideocreatewindowoptions) are of this type.
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 a window becomes visible.
650
+ Fired when the window becomes visible.
640
651
 
641
652
  ### Event: 'hide'
642
653
 
643
- Fired when a window becomes hidden.
654
+ Fired when the window becomes hidden.
644
655
 
645
656
  ### Event: 'expose'
646
657
 
647
- Fired when a window becomes exposed and should be redrawn.
658
+ Fired when the window becomes exposed and should be redrawn.
648
659
 
649
660
  ### Event: 'minimize'
650
661
 
651
- Fired when a window becomes minimized.
662
+ Fired when the window becomes minimized.
652
663
 
653
664
  ### Event: 'maximize'
654
665
 
655
- Fired when a window becomes maximized.
666
+ Fired when the window becomes maximized.
656
667
 
657
668
  ### Event: 'restore'
658
669
 
659
- Fired when a window gets restored.
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 a window moves from one display to another.
692
+ Fired when the window moves from one display to another.
682
693
 
683
694
  ### Event: 'focus'
684
695
 
685
- Fired when a window gains the keyboard focus.
696
+ Fired when the window gains the keyboard focus.
686
697
 
687
698
  ### Event: 'blur'
688
699
 
689
- Fired when a window loses the keyboard focus.
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 has requested the window to close (usually by clicking the "x" button).
704
- If you need to display any confirmation dialogs you should call `event.prevent()` and handle destruction manually.
705
- If `prevent` is not called, then this event will be followed by a [`'close'`](#event-close) event.
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 the user enters text via the keyboard.
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>` Will be `true` if the event was caused by a touch event.
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>` Will be `true` if the event was caused by a touch event.
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>` Will be `true` if the event was caused by a touch event.
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>` Will be `true` if the event was caused by a touch event.
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>` Will be `true` if the underlying platform reverses the mouse wheel's scroll direction. Multiply `dx` and `dy` by `-1` to get the correct values.
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 dropping a set of items onto a window, first the [`'dropBegin'`](#event-dropbegin) event will be fired, then a number of [`'dropText'`](#event-droptext) and/or [`'dropFile'`](#event-dropfile) events will be fired, corresponding to the contents of the drop, then finally the [`'dropComplete'`](#event-dropcomplete) event will be fired.
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. This will be larger than [`width`](#windowwidth) on [high-dpi](#high-dpi) displays.
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. This will be larger than [`height`](#windowheight) on [high-dpi](#high-dpi) displays.
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 this window belongs to.
885
- If the window spans multiple displays, then the display containing the center of the window is returned.
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
- Will be `true` if the window is visible.
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
- Will be `true` if the window is fullscreen.
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
- Will be `true` if the window is resizable.
921
- A resizable window can be resized by dragging it's borders.
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
- Will be `true` if the window is borderless.
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
- Will be `true` if the window was created with `alwaysOnTop: true`.
947
- Such a window will always be shown above other windows.
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
- Will be `true` if the window is using hardware accelerated rendering.
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
- Will be `true` if the window is using vsync.
968
- A window with vsync enabled will have its frame rate synchronized to the display's refresh rate to prevent tearing.
969
- Note that vsync can only be used if that window is also [`accelerated`](#windowaccelerated)
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
- Will be `true` if the window was created in OpenGl mode.
984
- In OpenGL mode, you can only render to the window with OpenGL calls.
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
- Will be `true` if the window was created in WebGPU mode.
992
- In WebGPU mode, you can only render to the window with WebGPU calls.
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
- This object might also include extra fields that are used for passing to [@kmamal/gl](https://github.com/kmamal/headless-gl#readme) or [@kmamal/gpu](https://github.com/kmamal/gpu#readme).
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
- Will be `true` if the window is maximized.
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
- Will be `true` if the window is minimized.
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's neither minimized nor maximized.
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
- Will be `true` if the window has keyboard input.
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
- Will be `true` if the mouse is over the window.
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
- Will be `true` if the window was created with `skipTaskbar: true`.
1052
- Such a window will not be added to the taskbar.
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
- Will be `true` if the window was created with `popupMenu: true`.
1060
- Such a window will always be treated as a popup menu.
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
- Will be `true` if the window was created with `tooltip: true`.
1068
- Such a window will always be treated as a tooltip.
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
- Will be `true` if the window was created with `utility: true`.
1076
- Such a window will always be treated as a utility 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 can pass the optional `dstRect` parameter to set where exactly on the window to display the image.
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,8 +1113,8 @@ 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 can only render to the window with OpenGL/WebGPU calls.
1103
- Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-options) will fail.
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.
1117
+ Calls to `render()` will fail.
1104
1118
 
1105
1119
  ### window.setIcon(width, height, stride, format, buffer)
1106
1120
 
@@ -1108,12 +1122,12 @@ Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-options) wi
1108
1122
 
1109
1123
  Set's the window's icon, usually displayed in the title bar and the taskbar.
1110
1124
 
1111
- ### window.flash(untilFocused)
1125
+ ### window.flash([untilFocused])
1112
1126
 
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 flash until the user focuses it.
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
- Will be `true` if the window is destroyed.
1127
- A destroyed window object should not be used any further.
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 will first make the window emit the [`'beforeClose'`](#event-beforeclose) event, giving you a chance to prevent the window from being destroyed.
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: the character that it produces ("a", "b", "@", " ", .e.t.c) or the function that it corresponds to ("Esc", "F4", "Ctrl", e.t.c.).
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 will be returned.
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 object representing the state of each key.
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
- The values will be `true` for keys that are pressed and `false` otherwise.
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>` Will be `true` if the button is pressed.
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 will be visible. Default: `true`
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 will be captured by the current window. Default: `true`
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
- * `guid: <string>` The GUID of the device.
1609
- * `type: <JoystickType>|<null>` The type of the device.
1610
- * `vendor: <number>|<null>` The USB vendor ID of the device. Will be `null` if it can't be determined.
1611
- * `product: <number>|<null>` The USB product ID of the device. Will be `null` if it can't be determined.
1612
- * `version: <number>|<null>` The USB product version of the device. Will be `null` if it can't be determined.
1613
- * `player: <number>|<null>` The player index for the device. Will be `null` if it can't be determined.
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 should be opened.
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 JoystickInstance
1671
+ ## class joystickInstance
1657
1672
 
1658
- This class is not directly exposed by the API so you can't use it with the `new` operator.
1659
- Instead, objects returned by [`sdl.joystick.openDevice()`](#sdljoystickopendevicedevice) are of this type.
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 this instance was opened.
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's not available..
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's not available.
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
- The values will be `true` for buttons that are pressed and `false` otherwise.
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 this joystick.
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
- Will be `true` if there is a LED light on the joystick, whose color can be controlled.
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
- Will be `true` if the joystick has rumble motors.
1804
+ Is `true` if the joystick has rumble motors.
1790
1805
 
1791
- ### joystickInstance.rumble([low, [high, [duration]]])
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
- Will be `true` if the joystick has rumble motors on the triggers.
1824
+ Is `true` if the joystick has rumble motors on the triggers.
1810
1825
 
1811
- ### joystickInstance.rumbleTriggers([left, [right, [duration]]])
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
- Will be `true` if the instance is closed.
1830
- A closed instance object should not be used any further.
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, it's name, and a series of pairings between one joystick axis/button and the corresponding controller axis/button name.
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
- You can add them via:
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 can cause already opened controller instances to be [remapped](#event-remap).
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
- * `guid: <string>` The GUID of the device.
1892
- * `type: <string>|null` The type of the device.
1893
- * `vendor: <number>|<null>` The USB vendor ID of the device. Will be `null` if it can't be determined.
1894
- * `product: <number>|<null>` The USB product ID of the device. Will be `null` if it can't be determined.
1895
- * `version: <number>|<null>` The USB product version of the device. Will be `null` if it can't be determined.
1896
- * `player: <number>|<null>` The player index for the device. Will be `null` if it can't be determined.
1897
- * `mapping: <string>` The axis and button mapping for this device.
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 should be opened.
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
- This class is not directly exposed by the API so you can't use it with the `new` operator.
1948
- Instead, objects returned by [`sdl.controller.openDevice()`](#sdlcontrolleropendevicedevice) are of this type.
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 this controller is applied (usually via [`sdl.controller.addMappings()`](#sdlcontrolleraddmappingsmappings)).
1978
- This can cause all of the controller's axes and buttons to aquire new values.
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 this instance was opened.
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's not available.
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's not available.
2010
- The `Buffer` will contain an `InputHandle_t` for the controller that can be used with the [Steam Input API](https://partner.steamgames.com/doc/api/ISteamInput)
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
- The values will be `true` for buttons that are pressed and `false` otherwise.
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 this controller.
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
- Will be `true` if there is a LED light on the controller, whose color can be controlled.
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
- Will be `true` if the controller has rumble motors.
2101
+ Is `true` if the controller has rumble motors.
2087
2102
 
2088
- ### controllerInstance.rumble([low, [high, [duration]]])
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
- Will be `true` if the controller has rumble motors on the triggers.
2121
+ Is `true` if the controller has rumble motors on the triggers.
2107
2122
 
2108
- ### controllerInstance.rumbleTriggers([left, [right, [duration]]])
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
- Will be `true` if the instance is closed.
2127
- A closed instance object should not be used any further.
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
- The readings from accelerometers will include the force of gravity, so a device at rest will have a value of `STANDARD_GRAVITY` away from the center of the earth.
2141
- Use this constant to correct for that if your application requires it.
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'`, `'gyroscope'`. Will be `null` if it can't be determined.
2149
- * `side: <string>|<null>` Some sensors (such as those on the Joy-Con controller) have a `'left'` or `'right'` side, otherwise this value will be `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 should be opened.
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
- This class is not directly exposed by the API so you can't use it with the `new` operator.
2166
- Instead, objects returned by [`sdl.sensor.openDevice()`](#sdlsensoropendevicedevice) are of this type.
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 this instance was opened.
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 this measurement was taken __in microseconds__, or `null` if that's not available.
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
- This measurement includes the force of gravity, so a device at rest will have an value of [`sdl.sensor.STANDARD_GRAVITY`](#sdlsensorstandard_gravity) away from the center of the earth.
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
- Will be `true` if the instance is closed.
2215
- A closed instance object should not be used any further.
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's first sample will be the one for the left channel, followed by the one for the right channel.
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 this event is emitted, all instances that were opened from the removed device are closed automatically.
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>` Will be either `'playback'` or `'recording'`.
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 this list can sometimes be empty.
2402
- Despite that, in many common cases, it is still possible to successfully open the default device by only passing `type` to [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) like this:
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>`: Should be either `'playback'` or `'recording'`.
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 that will be buffered by the driver. Must be a power of `2`. Default: `4096`
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 the returned object will be an [`AudioPlaybackInstance`](#class-audioplaybackinstance-extends-audioinstance), otherwise it will be an [`AudioRecordingInstance`](#class-audiorecordinginstance-extends-audioinstance).
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
- Most of the time you will be passing objects from [`sdl.audio.devices`](#sdlaudiodevices) as the first argument to this function.
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 will usually return an empty list for [`sdl.audio.devices`](#sdlaudiodevices).
2457
+ These drivers usually return an empty list for [`sdl.audio.devices`](#sdlaudiodevices).
2432
2458
 
2433
- The `channels`, `frequency` and `format` options together define what the data in the `Buffer` objects you read from or write to the instance will look like.
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" that you will experience between the application and the audio driver.
2437
- With smaller values you will have smaller delays, but you will also have to read/write data from/to the driver more frequently.
2438
- Applications such as virtual instruments that need to play audio in reaction to user input will want to change this option to lower values.
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
- This class is not directly exposed by the API so you can't use it with the `new` operator.
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 this instance was opened.
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
- Will be `true` if the instance is currently playing.
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 instance or dequeued by the user.
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
- Will be `true` if the instance is closed.
2563
- A closed instance object should not be used any further.
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
- This class is not directly exposed by the API so you can't use it with the `new` operator.
2573
- Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) are of this type, if a playback device is opened.
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 generated audio data from the buffer, and writes it to the queue, from which it will be played back.
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
- This class is not directly exposed by the API so you can't use it with the `new` operator.
2586
- Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) are of this type, if a recording device is opened.
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 been put on the queue, and writes it to the provided buffer.
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'`. Will be `null` if it can't be determinded.
2625
- * `seconds: <number>|<null>` Seconds of battery life left. Will be `null` if not running on battery, or if it can't be determinded.
2626
- * `percent: <number>|<null>` Percentage of battery life left. Will be `null` if not running on battery, or if it can't be determinded.
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 can only be imported from the main thread.
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 it's own instance of the module and it's hard to make them talk with each other).
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! Even if the threads do not have access to the SDL-related functions, they can still write data to buffers and then pass those buffers to the main thread from where they can be passed to SDL. One thing is missing: While the core of the library is not needed, it's nice to have the helper functions, for example when writing an audio renderer it's nice to have the [`readSample`](#sdlaudioreadsampleformat-buffer-offset), [`writeSample`](#sdlaudiowritesampleformat-buffer-value-offset), etc functions.
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. They are made available through the `@kmamal/sdl/helpers` sub-module that does not load any of the native code. For an example of their use see [this example](https://github.com/kmamal/node-sdl/blob/master/examples/12-audio-thread/audio-worker.js).
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 there are no prebuilt binaries available for your platform, `@kmamal/sdl` will try to compile itself during installation.
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, make sure you have installed [node-gyp](https://github.com/nodejs/node-gyp#installation) as well as its dependencies.
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 will also need to install `xquartz` so that SDL can find the X11 headers it needs.
2660
- You can do that via `brew install xquartz`.
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 will be downloaded automatically through the [@kmamal/build-sdl](https://github.com/kmamal/build-sdl) package.
2664
- If `@kmamal/build-sdl` has no prebuilt library for your platform, it will try to compile one on the spot.
2665
- You will need to have `cmake` installed for that to work.
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