@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/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
@@ -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>`
@@ -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
- 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).
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 can be `null`.
383
- This can happen on systems that don't have any compatible devices, such as on a CI pipeline.
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 will need to provide an image to the library:
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. 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.
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 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.
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>` 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`
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 this window above others. Default: `false`
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 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`
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
- * If you specify the `display` option, you can't also specify the `x` or `y` options, and vice-versa.
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 can only render to the window with OpenGL/WebGPU calls.
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
- 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.
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 a window becomes visible.
665
+ Fired when the window becomes visible.
640
666
 
641
667
  ### Event: 'hide'
642
668
 
643
- Fired when a window becomes hidden.
669
+ Fired when the window becomes hidden.
644
670
 
645
671
  ### Event: 'expose'
646
672
 
647
- Fired when a window becomes exposed and should be redrawn.
673
+ Fired when the window becomes exposed and should be redrawn.
648
674
 
649
675
  ### Event: 'minimize'
650
676
 
651
- Fired when a window becomes minimized.
677
+ Fired when the window becomes minimized.
652
678
 
653
679
  ### Event: 'maximize'
654
680
 
655
- Fired when a window becomes maximized.
681
+ Fired when the window becomes maximized.
656
682
 
657
683
  ### Event: 'restore'
658
684
 
659
- Fired when a window gets restored.
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 a window moves from one display to another.
707
+ Fired when the window moves from one display to another.
682
708
 
683
709
  ### Event: 'focus'
684
710
 
685
- Fired when a window gains the keyboard focus.
711
+ Fired when the window gains the keyboard focus.
686
712
 
687
713
  ### Event: 'blur'
688
714
 
689
- Fired when a window loses the keyboard focus.
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 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.
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 the user enters text via the keyboard.
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>` Will be `true` if the event was caused by a touch event.
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>` Will be `true` if the event was caused by a touch event.
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>` Will be `true` if the event was caused by a touch event.
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>` Will be `true` if the event was caused by a touch event.
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>` 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.
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 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.
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. This will be larger than [`width`](#windowwidth) on [high-dpi](#high-dpi) displays.
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. This will be larger than [`height`](#windowheight) on [high-dpi](#high-dpi) displays.
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 this window belongs to.
885
- If the window spans multiple displays, then the display containing the center of the window is returned.
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
- Will be `true` if the window is visible.
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
- Will be `true` if the window is fullscreen.
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
- Will be `true` if the window is resizable.
921
- A resizable window can be resized by dragging it's borders.
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
- Will be `true` if the window is borderless.
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
- Will be `true` if the window was created with `alwaysOnTop: true`.
947
- Such a window will always be shown above other windows.
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
- Will be `true` if the window is using hardware accelerated rendering.
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
- 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)
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
- 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.
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
- 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.
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
- 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.
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
- Will be `true` if the window is maximized.
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
- Will be `true` if the window is minimized.
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's neither minimized nor maximized.
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
- Will be `true` if the window has keyboard input.
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
- Will be `true` if the mouse is over the window.
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
- Will be `true` if the window was created with `skipTaskbar: true`.
1052
- Such a window will not be added to the taskbar.
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
- Will be `true` if the window was created with `popupMenu: true`.
1060
- Such a window will always be treated as a popup menu.
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
- Will be `true` if the window was created with `tooltip: true`.
1068
- Such a window will always be treated as a tooltip.
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
- Will be `true` if the window was created with `utility: true`.
1076
- Such a window will always be treated as a utility 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 can pass the optional `dstRect` parameter to set where exactly on the window to display the image.
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 can only render to the window with OpenGL/WebGPU calls.
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 flash until the user focuses it.
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
- Will be `true` if the window is destroyed.
1127
- A destroyed window object should not be used any further.
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 will first make the window emit the [`'beforeClose'`](#event-beforeclose) event, giving you a chance to prevent the window from being destroyed.
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: the character that it produces ("a", "b", "@", " ", .e.t.c) or the function that it corresponds to ("Esc", "F4", "Ctrl", e.t.c.).
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 will be returned.
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 object representing the state of each key.
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
- The values will be `true` for keys that are pressed and `false` otherwise.
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>` Will be `true` if the button is pressed.
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 will be visible. Default: `true`
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 will be captured by the current window. Default: `true`
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
- * `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.
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 should be opened.
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 JoystickInstance
1686
+ ## class joystickInstance
1657
1687
 
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.
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 this instance was opened.
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's not available..
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's not available.
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
- The values will be `true` for buttons that are pressed and `false` otherwise.
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 this joystick.
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
- Will be `true` if there is a LED light on the joystick, whose color can be controlled.
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
- Will be `true` if the joystick has rumble motors.
1819
+ Is `true` if the joystick has rumble motors.
1790
1820
 
1791
- ### joystickInstance.rumble([low, [high, [duration]]])
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
- Will be `true` if the joystick has rumble motors on the triggers.
1839
+ Is `true` if the joystick has rumble motors on the triggers.
1810
1840
 
1811
- ### joystickInstance.rumbleTriggers([left, [right, [duration]]])
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
- Will be `true` if the instance is closed.
1830
- A closed instance object should not be used any further.
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, it's name, and a series of pairings between one joystick axis/button and the corresponding controller axis/button name.
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
- You can add them via:
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 can cause already opened controller instances to be [remapped](#event-remap).
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
- * `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.
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 should be opened.
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
- 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.
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 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.
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 this instance was opened.
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's not available.
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'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)
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
- The values will be `true` for buttons that are pressed and `false` otherwise.
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 this controller.
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
- Will be `true` if there is a LED light on the controller, whose color can be controlled.
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
- Will be `true` if the controller has rumble motors.
2116
+ Is `true` if the controller has rumble motors.
2087
2117
 
2088
- ### controllerInstance.rumble([low, [high, [duration]]])
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
- Will be `true` if the controller has rumble motors on the triggers.
2136
+ Is `true` if the controller has rumble motors on the triggers.
2107
2137
 
2108
- ### controllerInstance.rumbleTriggers([left, [right, [duration]]])
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
- Will be `true` if the instance is closed.
2127
- A closed instance object should not be used any further.
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
- 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.
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'`, `'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`.
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 should be opened.
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
- 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.
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 this instance was opened.
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 this measurement was taken __in microseconds__, or `null` if that's not available.
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
- 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.
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
- Will be `true` if the instance is closed.
2215
- A closed instance object should not be used any further.
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's first sample will be the one for the left channel, followed by the one for the right channel.
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 this event is emitted, all instances that were opened from the removed device are closed automatically.
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>` Will be either `'playback'` or `'recording'`.
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 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:
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>`: Should be either `'playback'` or `'recording'`.
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 that will be buffered by the driver. Must be a power of `2`. Default: `4096`
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 the returned object will be an [`AudioPlaybackInstance`](#class-audioplaybackinstance-extends-audioinstance), otherwise it will be an [`AudioRecordingInstance`](#class-audiorecordinginstance-extends-audioinstance).
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
- 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:
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 will usually return an empty list for [`sdl.audio.devices`](#sdlaudiodevices).
2472
+ These drivers usually return an empty list for [`sdl.audio.devices`](#sdlaudiodevices).
2432
2473
 
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.
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" 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.
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
- This class is not directly exposed by the API so you can't use it with the `new` operator.
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 this instance was opened.
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
- Will be `true` if the instance is currently playing.
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 instance or dequeued by the user.
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
- Will be `true` if the instance is closed.
2563
- A closed instance object should not be used any further.
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
- 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.
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 generated audio data from the buffer, and writes it to the queue, from which it will be played back.
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
- 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.
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 been put on the queue, and writes it to the provided buffer.
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'`. 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.
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 can only be imported from the main thread.
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 it's own instance of the module and it's hard to make them talk with each other).
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! 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.
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. 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).
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 there are no prebuilt binaries available for your platform, `@kmamal/sdl` will try to compile itself during installation.
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, make sure you have installed [node-gyp](https://github.com/nodejs/node-gyp#installation) as well as its dependencies.
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 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`.
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 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.
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