@kmamal/sdl 0.5.2 → 0.6.1

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
@@ -5,17 +5,17 @@
5
5
  [![Vulnerabilities](https://img.shields.io/snyk/vulnerabilities/npm/%2540kmamal%252Fsdl)](https://snyk.io/test/npm/@kmamal/sdl)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
7
 
8
- SDL2 bindings for Node.js.
9
- Provides window management, input events, audio playback/recording, and clipboard manipulation.
10
- You can use it together with [@kmamal/gl](https://github.com/kmamal/headless-gl#readme) to get native WebGL drawing without having to use a browser.
8
+ SDL bindings for Node.js.
9
+ Provides window management, input events (keyboard, mouse, joystick, controller), audio playback and recording, and clipboard manipulation.
10
+ You can also use it together with [@kmamal/gl](https://github.com/kmamal/headless-gl#readme) to get native WebGL drawing without having to use a browser.
11
11
 
12
12
  It should work on Linux, Mac, and Windows.
13
- Prebuilt binaries are available for x64 architectures, as well as arm-based Macs.
13
+ Prebuilt binaries are available for x64 architectures, and arm-based Macs.
14
14
 
15
15
 
16
16
  ## Installation
17
17
 
18
- SDL2 is bundled along with the binaries so a separate installation is not necessary.
18
+ SDL is bundled along with the binaries so a separate installation is not necessary.
19
19
  This package is self-contained.
20
20
  Just run:
21
21
 
@@ -23,17 +23,25 @@ Just run:
23
23
  npm install @kmamal/sdl
24
24
  ```
25
25
 
26
- (But if things go wrong do look over [here](#installing-sdl2))
26
+ (But if things go wrong do look over [here](#building-from-source))
27
27
 
28
28
 
29
- ## Example
29
+ ## "Hello, World!" example
30
30
 
31
+ ```js
32
+ const sdl = require('@kmamal/sdl')
33
+
34
+ const window = sdl.video.createWindow({ title: "Hello, World!" })
35
+ window.on('*', console.log)
36
+ ```
37
+
38
+ ## WebGL example
31
39
  ```js
32
40
  const sdl = require('@kmamal/sdl')
33
41
  const createContext = require('@kmamal/gl')
34
42
 
35
43
  const window = sdl.video.createWindow({
36
- title: "Hello, World!"
44
+ title: "WebGL!",
37
45
  opengl: true,
38
46
  })
39
47
 
@@ -126,20 +134,102 @@ There are more examples [in the `examples/` folder](https://github.com/kmamal/no
126
134
  * [window.setIcon(width, height, stride, format, buffer)](#windowseticonwidth-height-stride-format-buffer)
127
135
  * [window.destroyed](#windowdestroyed)
128
136
  * [window.destroy()](#windowdestroy)
137
+ * [sdl.keyboard](#sdlkeyboard)
138
+ * [Virtual keys](#virtual-keys)
139
+ * [Enum: SCANCODE](#enum-scancode)
140
+ * [sdl.keyboard.getKey(scancode)](#sdlkeyboardgetkeyscancode)
141
+ * [sdl.keyboard.getScancode(key)](#sdlkeyboardgetscancodekey)
142
+ * [sdl.keyboard.getState()](#sdlkeyboardgetstate)
143
+ * [sdl.mouse](#sdlmouse)
144
+ * [Mouse cursors](#mouse-cursors)
145
+ * [Enum: BUTTON](#enum-button)
146
+ * [sdl.mouse.getButton(button)](#sdlmousegetbuttonbutton)
147
+ * [sdl.mouse.position](#sdlmouseposition)
148
+ * [sdl.mouse.setPosition(x, y)](#sdlmousesetpositionx-y)
149
+ * [sdl.mouse.setCursor(cursor)](#sdlmousesetcursor)
150
+ * [sdl.mouse.setCursorImage(width, height, stride, format, buffer, x, y)](#sdlmousesetcursorimagewidth-height-stride-format-buffer-x-y)
151
+ * [sdl.mouse.showCursor([show])](#sdlmouseshowcursorshow)
152
+ * [sdl.mouse.hideCursor()](#sdlmousehidecursor)
153
+ * [sdl.mouse.capture([capture])](#sdlmousecapturecapture)
154
+ * [sdl.mouse.uncapture()](#sdlmousecapture)
155
+ * [sdl.joystick](#sdljoystick)
156
+ * [Joystick types](#joystick-types)
157
+ * [Hat positions](#hat-positions)
158
+ * [Power levels](#power-levels)
159
+ * [Event: 'deviceAdd'](#joystick-event-device-add)
160
+ * [Event: 'deviceRemove'](#joystick-event-device-remove)
161
+ * [sdl.joystick.devices](#sdljoystickdevices)
162
+ * [sdl.joystick.openDevice(device)](#sdljoystickopendevicedevice)
163
+ * [class JoystickInstance](#class-joystickinstance)
164
+ * [Event: 'axisMotion'](#joystick-instance-event-axismotion)
165
+ * [Event: 'ballMotion'](#event-ballmotion)
166
+ * [Event: 'buttonDown'](#joystick-instance-event-buttondown)
167
+ * [Event: 'buttonUp'](#joystick-instance-event-buttonup)
168
+ * [Event: 'hatMotion'](#event-hatmotion)
169
+ * [Event: 'close'](#joystick-instance-event-close)
170
+ * [joystickInstance.device](#joystickinstancedevice)
171
+ * [joystickInstance.firmwareVersion](#joystickinstancefirmwareversion)
172
+ * [joystickInstance.serialNumber](#joystickinstanceserialnumber)
173
+ * [joystickInstance.axes](#joystickinstanceaxes)
174
+ * [joystickInstance.balls](#joystickinstanceballs)
175
+ * [joystickInstance.buttons](#joystickinstancebuttons)
176
+ * [joystickInstance.hats](#joystickinstancehats)
177
+ * [joystickInstance.power](#joystickinstancepower)
178
+ * [joystickInstance.hasLed](#joystickinstancehasled)
179
+ * [joystickInstance.setLed(red, green, blue)](#joystickinstancesetledredgreenblue)
180
+ * [joystickInstance.hasRumble](#joystickinstancehasrumble)
181
+ * [joystickInstance.rumble([low[, high[, duration]]])](#joystickinstancerumblelowhighduration)
182
+ * [joystickInstance.stopRumble()](#joystickinstancestoprumble)
183
+ * [joystickInstance.hasRumbleTriggers](#joystickinstancehasrumbletriggers)
184
+ * [joystickInstance.rumbleTriggers([left[, right[, duration]]])](#joystickinstancerumbletriggersleftrightduration)
185
+ * [joystickInstance.stopRumbleTriggers()](#joystickinstancestoprumbletriggers)
186
+ * [joystickInstance.closed](#joystickinstanceclosed)
187
+ * [joystickInstance.close()](#joystickinstanceclose)
188
+ * [sdl.controller](#sdlcontroller)
189
+ * [Event: 'deviceAdd'](#controller-event-device-add)
190
+ * [Event: 'deviceRemove'](#controller-event-device-remove)
191
+ * [sdl.controller.addMappings(mappings)](#sdlcontrolleraddmappingsmappings)
192
+ * [sdl.controller.devices](#sdlcontrollerdevices)
193
+ * [sdl.controller.openDevice(device)](#sdlcontrolleropendevicedevice)
194
+ * [class ControllerInstance](#class-controllerinstance)
195
+ * [Event: 'axisMotion'](#controller-instance-event-axismotion)
196
+ * [Event: 'buttonDown'](#controller-instance-event-buttondown)
197
+ * [Event: 'buttonUp'](#controller-instance-event-buttonup)
198
+ * [Event: 'remap'](#event-remap)
199
+ * [Event: 'close'](#controller-instance-event-close)
200
+ * [controllerInstance.device](#controllerinstancedevice)
201
+ * [controllerInstance.firmwareVersion](#controllerinstancefirmwareversion)
202
+ * [controllerInstance.serialNumber](#controllerinstanceserialnumber)
203
+ * [controllerInstance.axes](#controllerinstanceaxes)
204
+ * [controllerInstance.buttons](#controllerinstancebuttons)
205
+ * [controllerInstance.power](#controllerinstancepower)
206
+ * [controllerInstance.hasLed](#controllerinstancehasled)
207
+ * [controllerInstance.setLed(red, green, blue)](#controllerinstancesetledredgreenblue)
208
+ * [controllerInstance.hasRumble](#controllerinstancehasrumble)
209
+ * [controllerInstance.rumble([low[, high[, duration]]])](#controllerinstancerumblelowhighduration)
210
+ * [controllerInstance.stopRumble()](#controllerinstancestoprumble)
211
+ * [controllerInstance.hasRumbleTriggers](#controllerinstancehasrumbletriggers)
212
+ * [controllerInstance.rumbleTriggers([left[, right[, duration]]])](#controllerinstancerumbletriggersleftrightduration)
213
+ * [controllerInstance.stopRumbleTriggers()](#controllerinstancestoprumbletriggers)
214
+ * [controllerInstance.closed](#controllerinstanceclosed)
215
+ * [controllerInstance.close()](#controllerinstanceclose)
129
216
  * [sdl.audio](#sdlaudio)
130
217
  * [Audio data](#audio-data)
131
218
  * [Sample formats](#sample-formats)
132
- * [Event: 'deviceAdd'](#event-deviceadd)
133
- * [Event: 'deviceRemove'](#event-deviceremove)
219
+ * [Event: 'deviceAdd'](#audio-event-device-add)
220
+ * [Event: 'deviceRemove'](#audio-event-device-remove)
134
221
  * [sdl.audio.bytesPerSample(format)](#sdlaudiobytespersampleformat)
135
222
  * [sdl.audio.minSampleValue(format)](#sdlaudiominsamplevalueformat)
136
223
  * [sdl.audio.maxSampleValue(format)](#sdlaudiomaxsamplevalueformat)
137
224
  * [sdl.audio.zeroSampleValue(format)](#sdlaudiozerosamplevalueformat)
138
225
  * [sdl.audio.readSample(format, buffer[, offset])](#sdlaudioreadsampleformat-buffer-offset)
226
+ * [sdl.audio.readerName(format)](#sdlaudioreadernameformat)
139
227
  * [sdl.audio.writeSample(format, buffer, value[, offset])](#sdlaudiowritesampleformat-buffer-value-offset)
228
+ * [sdl.audio.writerName(format)](#sdlaudiowriternameformat)
140
229
  * [sdl.audio.devices](#sdlaudiodevices)
141
230
  * [sdl.audio.openDevice(device[, options])](#sdlaudioopendevicedevice-options)
142
231
  * [class AudioInstance](#class-audioinstance)
232
+ * [Event: 'close'](#audio-instance-event-close)
143
233
  * [audioInstance.id](#audioinstanceid)
144
234
  * [audioInstance.name](#audioinstancename)
145
235
  * [audioInstance.channels](#audioinstancechannels)
@@ -150,7 +240,9 @@ There are more examples [in the `examples/` folder](https://github.com/kmamal/no
150
240
  * [audioInstance.maxSampleValue](#audioinstancemaxsamplevalue)
151
241
  * [audioInstance.zeroSampleValue](#audioinstancezerosamplevalue)
152
242
  * [audioInstance.readSample(buffer[, offset])](#audioinstancereadsamplebuffer-offset)
243
+ * [audioInstance.readerName](#audioinstancereadername)
153
244
  * [audioInstance.writeSample(buffer, value[, offset])](#audioinstancewritesamplebuffer-value-offset)
245
+ * [audioInstance.writerName](#audioinstancewritername)
154
246
  * [audioInstance.buffered](#audioinstancebuffered)
155
247
  * [audioInstance.playing](#audioinstanceplaying)
156
248
  * [audioInstance.play([play])](#audioinstanceplayplay)
@@ -163,24 +255,6 @@ There are more examples [in the `examples/` folder](https://github.com/kmamal/no
163
255
  * [playbackInstance.enqueue(buffer[, bytes])](#playbackinstanceenqueuebuffer-bytes)
164
256
  * [class AudioRecordingInstance extends AudioInstance](#class-audiorecordinginstance-extends-audioinstance)
165
257
  * [recordingInstance.dequeue(buffer[, bytes])](#recordinginstancedequeuebuffer-bytes)
166
- * [sdl.keyboard](#sdlkeyboard)
167
- * [Virtual keys](#virtual-keys)
168
- * [Enum: SCANCODE](#enum-scancode)
169
- * [sdl.keyboard.getKey(scancode)](#sdlkeyboardgetkeyscancode)
170
- * [sdl.keyboard.getScancode(key)](#sdlkeyboardgetscancodekey)
171
- * [sdl.keyboard.getState()](#sdlkeyboardgetstate)
172
- * [sdl.mouse](#sdlmouse)
173
- * [Mouse cursors](#mouse-cursors)
174
- * [Enum: BUTTON](#enum-buttons)
175
- * [sdl.mouse.getButton(button)](#sdlmousegetbuttonbutton)
176
- * [sdl.mouse.position](#sdlmouseposition)
177
- * [sdl.mouse.setPosition(x, y)](#sdlmousesetpositionx-y)
178
- * [sdl.mouse.setCursor(cursor)](#sdlmousesetcursor)
179
- * [sdl.mouse.setCursorImage(width, height, stride, format, buffer, x, y)](#sdlmousesetcursorimagewidth-height-stride-format-buffer-x-y)
180
- * [sdl.mouse.showCursor([show])](#sdlmouseshowcursorshow)
181
- * [sdl.mouse.hideCursor()](#sdlmousehidecursor)
182
- * [sdl.mouse.capture([capture])](#sdlmousecapturecapture)
183
- * [sdl.mouse.uncapture()](#sdlmousecapture)
184
258
  * [sdl.clipboard](#sdlclipboard)
185
259
  * [Event: 'update'](#event-update)
186
260
  * [sdl.clipboard.text](#sdlclipboardtext)
@@ -207,9 +281,9 @@ This event will be followed by a call to `process.exit()`.
207
281
 
208
282
  * `<object>`
209
283
  * `version: <object>`
210
- * `compile: <object>` The SDL2 version the bindings were compiled against.
284
+ * `compile: <object>` The SDL version the bindings were compiled against.
211
285
  * `major, minor, patch: <semver>` The components of the version.
212
- * `runtime: <object>` The SDL2 version of the dynamic library the is loaded.
286
+ * `runtime: <object>` The SDL version of the dynamic library the is loaded.
213
287
  * `major, minor, patch: <semver>` The components of the version.
214
288
  * `platform: <string>` The name of the platform we are running on. Possible values are: `'Linux'`, `'Windows'`, and `'Mac OS X'`.
215
289
  * `drivers: <object>`
@@ -220,9 +294,9 @@ This event will be followed by a call to `process.exit()`.
220
294
  * `all: <string>[]` A list of all audio drivers.
221
295
  * `current: <string>` The audio driver that is currently selected.
222
296
 
223
- This object is filled with the information produced during the initialization of SDL2.
297
+ This object is filled with the information produced during the initialization of SDL.
224
298
  All the values will remain constant throughout the execution of the program.
225
- If you want to initialize SDL2 with drivers other than the default ones, you can do so via its [environment variables](https://wiki.libsdl.org/FAQUsingSDL).
299
+ 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).
226
300
 
227
301
  Sample data for Ubuntu:
228
302
 
@@ -406,7 +480,7 @@ Creates a new window.
406
480
 
407
481
  The following restrictions apply:
408
482
  * If you specify the `display` option, you can't also specify the `x` or `y` options, and vice-versa.
409
- * The `resizable` and `borderless` options can't both be true.
483
+ * The `resizable` and `borderless` options are mutually exclusive.
410
484
  * The `vsync` option only applies to windows that are also `accelerated`.
411
485
 
412
486
  If you set the `opengl` option, then you can only render to the window with OpenGL calls.
@@ -795,194 +869,1153 @@ A destroyed window object should not be used any further.
795
869
  Destroys the window.
796
870
 
797
871
 
798
- ## sdl.audio
872
+ ## sdl.keyboard
799
873
 
800
- ### Audio data
874
+ There are three levels at which you can deal with the keyboard: physical keys ([scancodes](#enum-scancode)), virtual keys ([keys](#virtual-keys)), and text ([`'textInput'`](#event-textinput) events).
801
875
 
802
- The [`playbackInstance.enqueue()`](#playbackinstanceenqueuebuffer-bytes) function expects a buffer of audio data as input and the [`recordingInstance.dequeue()`](#recordinginstancedequeuebuffer-bytes) function returns a buffer of audio data as output.
803
- The format of the data in these buffers depends on the options you passed to [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options).
876
+ On the physical level, each of the physical keys corresponds to a number: the key's scancode.
877
+ For any given keyboard, the same key will always produce the same scancode.
878
+ If your application cares about the layout of the keyboard (for example using the "WASD" keys as a substitute for arrow keys), then you should handle key events at this level using the `scancode` property of [`'keyDown'`](#event-keydown) and [`'keyUp'`](#event-keyup) events.
804
879
 
805
- Audio data are a sequence of frames, with each frame being a sequence of samples.
806
- A _sample_ is a single number representing the intensity of a single audio channel at a specific point in time.
807
- For audio with multiple channels, each point in time is represented by one sample per channel.
808
- This is called a _frame_.
809
- The samples in a frame are arranged as follows:
810
- * For 1 channel (mono) a frame contains just the one sample.
811
- * 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.
812
- * For 4 channels (quad) the layout is front-left, front-right, rear-left, rear-right.
813
- * For 6 channels (5.1) the layout is front-left, front-right, center, low-freq, rear-left, rear-right.
880
+ 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.
814
881
 
815
- So for example, to fill a buffer with 3 seconds of a 440Hz sine wave, you could do:
882
+ 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.).
883
+ Your operating system provides a "keyboard mapping" that associates physical keys with their corresponding meaning.
884
+ 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).
885
+ These meanings are represented as [virtual key strings](#virtual-keys).
886
+ If your application cares about the meaning associated with individual keys then you should handle key events at this level using the `key` property of [`'keyDown'`](#event-keydown) and [`'keyUp'`](#event-keyup) events.
816
887
 
817
- ```js
818
- const TWO_PI = 2 * Math.PI
888
+ Note that not all physical keys correspond to a well-defined meaning and thus don't have a virtual key value associated with them.
889
+ The key events for these keys will have a `null` value for the `key` property.
819
890
 
820
- const {
821
- channels,
822
- frequency,
823
- bytesPerSample,
824
- minSampleValue,
825
- maxSampleValue,
826
- zeroSampleValue,
827
- } = playbackInstance
891
+ But sometimes the application doesn't care about individual keys at all, but about the resulting text that the user is entering.
892
+ Consider for example what happens when a user on a Greek keyboard layout enters an accent mark "´" followed by the letter "α" to produce the character "ά": Two keys were pressed, but only a single character was produced.
893
+ Trying to handle text input by manually translating key presses to text is not a very viable solution.
894
+ It's better to let the OS handle all the text logic, and get the final text by handling the rasulting ([`'textInput'`](#event-textinput)) events.
828
895
 
829
- const range = maxSampleValue - minSampleValue
830
- const amplitude = range / 2
831
896
 
832
- const sineAmplitude = 0.3 * amplitude
833
- const sineNote = 440
834
- const sinePeriod = 1 / sineNote
897
+ ### Enum: SCANCODE
835
898
 
836
- const duration = 3
837
- const numFrames = duration * frequency
838
- const numSamples = numFrames * channels
839
- const numBytes = numSamples * bytesPerSample
840
- const buffer = Buffer.alloc(numBytes)
899
+ Used to represent physical keys on the keyboard.
900
+ The same key will always produce the same scancode.
901
+ Values are based on the [USB usage page standard](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf).
841
902
 
842
- let offset = 0
843
- for (let i = 0; i < numFrames; i++) {
844
- const time = i / frequency
845
- const angle = time / sinePeriod * TWO_PI
846
- const sample = zeroSampleValue + Math.sin(angle) * sineAmplitude
847
- for (let j = 0; j < channels; j++) {
848
- offset = playbackInstance.writeSample(buffer, sample, offset)
849
- }
850
- }
851
- ```
903
+ <details>
904
+ <summary>Click to expand table</summary>
905
+
906
+ | Value | Corresponding `SDL_Scancode` | Comment |
907
+ | --- | --- | --- |
908
+ | `sdl.keyboard.SCANCODE.UNKNOWN` | `SDL_SCANCODE_UNKNOWN` | value `0` |
909
+ | `sdl.keyboard.SCANCODE.A` | `SDL_SCANCODE_A` | |
910
+ | `sdl.keyboard.SCANCODE.B` | `SDL_SCANCODE_B` | |
911
+ | `sdl.keyboard.SCANCODE.C` | `SDL_SCANCODE_C` | |
912
+ | `sdl.keyboard.SCANCODE.D` | `SDL_SCANCODE_D` | |
913
+ | `sdl.keyboard.SCANCODE.E` | `SDL_SCANCODE_E` | |
914
+ | `sdl.keyboard.SCANCODE.F` | `SDL_SCANCODE_F` | |
915
+ | `sdl.keyboard.SCANCODE.G` | `SDL_SCANCODE_G` | |
916
+ | `sdl.keyboard.SCANCODE.H` | `SDL_SCANCODE_H` | |
917
+ | `sdl.keyboard.SCANCODE.I` | `SDL_SCANCODE_I` | |
918
+ | `sdl.keyboard.SCANCODE.J` | `SDL_SCANCODE_J` | |
919
+ | `sdl.keyboard.SCANCODE.K` | `SDL_SCANCODE_K` | |
920
+ | `sdl.keyboard.SCANCODE.L` | `SDL_SCANCODE_L` | |
921
+ | `sdl.keyboard.SCANCODE.M` | `SDL_SCANCODE_M` | |
922
+ | `sdl.keyboard.SCANCODE.N` | `SDL_SCANCODE_N` | |
923
+ | `sdl.keyboard.SCANCODE.O` | `SDL_SCANCODE_O` | |
924
+ | `sdl.keyboard.SCANCODE.P` | `SDL_SCANCODE_P` | |
925
+ | `sdl.keyboard.SCANCODE.Q` | `SDL_SCANCODE_Q` | |
926
+ | `sdl.keyboard.SCANCODE.R` | `SDL_SCANCODE_R` | |
927
+ | `sdl.keyboard.SCANCODE.S` | `SDL_SCANCODE_S` | |
928
+ | `sdl.keyboard.SCANCODE.T` | `SDL_SCANCODE_T` | |
929
+ | `sdl.keyboard.SCANCODE.U` | `SDL_SCANCODE_U` | |
930
+ | `sdl.keyboard.SCANCODE.V` | `SDL_SCANCODE_V` | |
931
+ | `sdl.keyboard.SCANCODE.W` | `SDL_SCANCODE_W` | |
932
+ | `sdl.keyboard.SCANCODE.X` | `SDL_SCANCODE_X` | |
933
+ | `sdl.keyboard.SCANCODE.Y` | `SDL_SCANCODE_Y` | |
934
+ | `sdl.keyboard.SCANCODE.Z` | `SDL_SCANCODE_Z` | |
935
+ | `sdl.keyboard.SCANCODE.1` | `SDL_SCANCODE_1` | |
936
+ | `sdl.keyboard.SCANCODE.2` | `SDL_SCANCODE_2` | |
937
+ | `sdl.keyboard.SCANCODE.3` | `SDL_SCANCODE_3` | |
938
+ | `sdl.keyboard.SCANCODE.4` | `SDL_SCANCODE_4` | |
939
+ | `sdl.keyboard.SCANCODE.5` | `SDL_SCANCODE_5` | |
940
+ | `sdl.keyboard.SCANCODE.6` | `SDL_SCANCODE_6` | |
941
+ | `sdl.keyboard.SCANCODE.7` | `SDL_SCANCODE_7` | |
942
+ | `sdl.keyboard.SCANCODE.8` | `SDL_SCANCODE_8` | |
943
+ | `sdl.keyboard.SCANCODE.9` | `SDL_SCANCODE_9` | |
944
+ | `sdl.keyboard.SCANCODE.0` | `SDL_SCANCODE_0` | |
945
+ | `sdl.keyboard.SCANCODE.RETURN` | `SDL_SCANCODE_RETURN` | |
946
+ | `sdl.keyboard.SCANCODE.ESCAPE` | `SDL_SCANCODE_ESCAPE` | |
947
+ | `sdl.keyboard.SCANCODE.BACKSPACE` | `SDL_SCANCODE_BACKSPACE` | |
948
+ | `sdl.keyboard.SCANCODE.TAB` | `SDL_SCANCODE_TAB` | |
949
+ | `sdl.keyboard.SCANCODE.SPACE` | `SDL_SCANCODE_SPACE` | |
950
+ | `sdl.keyboard.SCANCODE.MINUS` | `SDL_SCANCODE_MINUS` | |
951
+ | `sdl.keyboard.SCANCODE.EQUALS` | `SDL_SCANCODE_EQUALS` | |
952
+ | `sdl.keyboard.SCANCODE.LEFTBRACKET` | `SDL_SCANCODE_LEFTBRACKET` | |
953
+ | `sdl.keyboard.SCANCODE.RIGHTBRACKET` | `SDL_SCANCODE_RIGHTBRACKET` | |
954
+ | `sdl.keyboard.SCANCODE.BACKSLASH` | `SDL_SCANCODE_BACKSLASH` | Located at the lower left of the return key on ISO keyboards and at the right end of the QWERTY row on ANSI keyboards. Produces REVERSE SOLIDUS (backslash) and VERTICAL LINE in a US layout, REVERSE SOLIDUS and VERTICAL LINE in a UK Mac layout, NUMBER SIGN and TILDE in a UK Windows layout, DOLLAR SIGN and POUND SIGN in a Swiss German layout, NUMBER SIGN and APOSTROPHE in a German layout, GRAVE ACCENT and POUND SIGN in a French Mac layout, and ASTERISK and MICRO SIGN in a French Windows layout. |
955
+ | `sdl.keyboard.SCANCODE.NONUSHASH` | `SDL_SCANCODE_NONUSHASH` | ISO USB keyboards actually use this code instead of 49 for the same key, but all OSes I've seen treat the two codes identically. So, as an implementor, unless your keyboard generates both of those codes and your OS treats them differently, you should generate SDL_SCANCODE_BACKSLASH instead of this code. As a user, you should not rely on this code because SDL will never generate it with most (all?) keyboards. |
956
+ | `sdl.keyboard.SCANCODE.SEMICOLON` | `SDL_SCANCODE_SEMICOLON` | |
957
+ | `sdl.keyboard.SCANCODE.APOSTROPHE` | `SDL_SCANCODE_APOSTROPHE` | |
958
+ | `sdl.keyboard.SCANCODE.GRAVE` | `SDL_SCANCODE_GRAVE` | Located in the top left corner (on both ANSI and ISO keyboards). Produces GRAVE ACCENT and TILDE in a US Windows layout and in US and UK Mac layouts on ANSI keyboards, GRAVE ACCENT and NOT SIGN in a UK Windows layout, SECTION SIGN and PLUS-MINUS SIGN in US and UK Mac layouts on ISO keyboards, SECTION SIGN and DEGREE SIGN in a Swiss German layout (Mac: only on ISO keyboards), CIRCUMFLEX ACCENT and DEGREE SIGN in a German layout (Mac: only on ISO keyboards), SUPERSCRIPT TWO and TILDE in a French Windows layout, COMMERCIAL AT and NUMBER SIGN in a French Mac layout on ISO keyboards, and LESS-THAN SIGN and GREATER-THAN SIGN in a Swiss German, German, or French Mac layout on ANSI keyboards. |
959
+ | `sdl.keyboard.SCANCODE.COMMA` | `SDL_SCANCODE_COMMA` | |
960
+ | `sdl.keyboard.SCANCODE.PERIOD` | `SDL_SCANCODE_PERIOD` | |
961
+ | `sdl.keyboard.SCANCODE.SLASH` | `SDL_SCANCODE_SLASH` | |
962
+ | `sdl.keyboard.SCANCODE.CAPSLOCK` | `SDL_SCANCODE_CAPSLOCK` | |
963
+ | `sdl.keyboard.SCANCODE.F1` | `SDL_SCANCODE_F1` | |
964
+ | `sdl.keyboard.SCANCODE.F2` | `SDL_SCANCODE_F2` | |
965
+ | `sdl.keyboard.SCANCODE.F3` | `SDL_SCANCODE_F3` | |
966
+ | `sdl.keyboard.SCANCODE.F4` | `SDL_SCANCODE_F4` | |
967
+ | `sdl.keyboard.SCANCODE.F5` | `SDL_SCANCODE_F5` | |
968
+ | `sdl.keyboard.SCANCODE.F6` | `SDL_SCANCODE_F6` | |
969
+ | `sdl.keyboard.SCANCODE.F7` | `SDL_SCANCODE_F7` | |
970
+ | `sdl.keyboard.SCANCODE.F8` | `SDL_SCANCODE_F8` | |
971
+ | `sdl.keyboard.SCANCODE.F9` | `SDL_SCANCODE_F9` | |
972
+ | `sdl.keyboard.SCANCODE.F10` | `SDL_SCANCODE_F10` | |
973
+ | `sdl.keyboard.SCANCODE.F11` | `SDL_SCANCODE_F11` | |
974
+ | `sdl.keyboard.SCANCODE.F12` | `SDL_SCANCODE_F12` | |
975
+ | `sdl.keyboard.SCANCODE.PRINTSCREEN` | `SDL_SCANCODE_PRINTSCREEN` | |
976
+ | `sdl.keyboard.SCANCODE.SCROLLLOCK` | `SDL_SCANCODE_SCROLLLOCK` | |
977
+ | `sdl.keyboard.SCANCODE.PAUSE` | `SDL_SCANCODE_PAUSE` | |
978
+ | `sdl.keyboard.SCANCODE.INSERT` | `SDL_SCANCODE_INSERT` | insert on PC, help on some Mac keyboards |
979
+ | `sdl.keyboard.SCANCODE.HOME` | `SDL_SCANCODE_HOME` | |
980
+ | `sdl.keyboard.SCANCODE.PAGEUP` | `SDL_SCANCODE_PAGEUP` | |
981
+ | `sdl.keyboard.SCANCODE.DELETE` | `SDL_SCANCODE_DELETE` | |
982
+ | `sdl.keyboard.SCANCODE.END` | `SDL_SCANCODE_END` | |
983
+ | `sdl.keyboard.SCANCODE.PAGEDOWN` | `SDL_SCANCODE_PAGEDOWN` | |
984
+ | `sdl.keyboard.SCANCODE.RIGHT` | `SDL_SCANCODE_RIGHT` | |
985
+ | `sdl.keyboard.SCANCODE.LEFT` | `SDL_SCANCODE_LEFT` | |
986
+ | `sdl.keyboard.SCANCODE.DOWN` | `SDL_SCANCODE_DOWN` | |
987
+ | `sdl.keyboard.SCANCODE.UP` | `SDL_SCANCODE_UP` | |
988
+ | `sdl.keyboard.SCANCODE.NUMLOCKCLEAR` | `SDL_SCANCODE_NUMLOCKCLEAR` | num lock on PC, clear on Mac keyboards |
989
+ | `sdl.keyboard.SCANCODE.KP_DIVIDE` | `SDL_SCANCODE_KP_DIVIDE` | |
990
+ | `sdl.keyboard.SCANCODE.KP_MULTIPLY` | `SDL_SCANCODE_KP_MULTIPLY` | |
991
+ | `sdl.keyboard.SCANCODE.KP_MINUS` | `SDL_SCANCODE_KP_MINUS` | |
992
+ | `sdl.keyboard.SCANCODE.KP_PLUS` | `SDL_SCANCODE_KP_PLUS` | |
993
+ | `sdl.keyboard.SCANCODE.KP_ENTER` | `SDL_SCANCODE_KP_ENTER` | |
994
+ | `sdl.keyboard.SCANCODE.KP_1` | `SDL_SCANCODE_KP_1` | |
995
+ | `sdl.keyboard.SCANCODE.KP_2` | `SDL_SCANCODE_KP_2` | |
996
+ | `sdl.keyboard.SCANCODE.KP_3` | `SDL_SCANCODE_KP_3` | |
997
+ | `sdl.keyboard.SCANCODE.KP_4` | `SDL_SCANCODE_KP_4` | |
998
+ | `sdl.keyboard.SCANCODE.KP_5` | `SDL_SCANCODE_KP_5` | |
999
+ | `sdl.keyboard.SCANCODE.KP_6` | `SDL_SCANCODE_KP_6` | |
1000
+ | `sdl.keyboard.SCANCODE.KP_7` | `SDL_SCANCODE_KP_7` | |
1001
+ | `sdl.keyboard.SCANCODE.KP_8` | `SDL_SCANCODE_KP_8` | |
1002
+ | `sdl.keyboard.SCANCODE.KP_9` | `SDL_SCANCODE_KP_9` | |
1003
+ | `sdl.keyboard.SCANCODE.KP_0` | `SDL_SCANCODE_KP_0` | |
1004
+ | `sdl.keyboard.SCANCODE.KP_PERIOD` | `SDL_SCANCODE_KP_PERIOD` | |
1005
+ | `sdl.keyboard.SCANCODE.NONUSBACKSLASH` | `SDL_SCANCODE_NONUSBACKSLASH` | This is the additional key that ISO keyboards have over ANSI ones, located between left shift and Y. Produces GRAVE ACCENT and TILDE in a US or UK Mac layout, REVERSE SOLIDUS (backslash) and VERTICAL LINE in a US or UK Windows layout, and LESS-THAN SIGN and GREATER-THAN SIGN in a Swiss German, German, or French layout. |
1006
+ | `sdl.keyboard.SCANCODE.APPLICATION` | `SDL_SCANCODE_APPLICATION` | windows contextual menu, compose |
1007
+ | `sdl.keyboard.SCANCODE.POWER` | `SDL_SCANCODE_POWER` | The USB document says this is a status flag, not a physical key - but some Mac keyboards do have a power key. |
1008
+ | `sdl.keyboard.SCANCODE.KP_EQUALS` | `SDL_SCANCODE_KP_EQUALS` | |
1009
+ | `sdl.keyboard.SCANCODE.F13` | `SDL_SCANCODE_F13` | |
1010
+ | `sdl.keyboard.SCANCODE.F14` | `SDL_SCANCODE_F14` | |
1011
+ | `sdl.keyboard.SCANCODE.F15` | `SDL_SCANCODE_F15` | |
1012
+ | `sdl.keyboard.SCANCODE.F16` | `SDL_SCANCODE_F16` | |
1013
+ | `sdl.keyboard.SCANCODE.F17` | `SDL_SCANCODE_F17` | |
1014
+ | `sdl.keyboard.SCANCODE.F18` | `SDL_SCANCODE_F18` | |
1015
+ | `sdl.keyboard.SCANCODE.F19` | `SDL_SCANCODE_F19` | |
1016
+ | `sdl.keyboard.SCANCODE.F20` | `SDL_SCANCODE_F20` | |
1017
+ | `sdl.keyboard.SCANCODE.F21` | `SDL_SCANCODE_F21` | |
1018
+ | `sdl.keyboard.SCANCODE.F22` | `SDL_SCANCODE_F22` | |
1019
+ | `sdl.keyboard.SCANCODE.F23` | `SDL_SCANCODE_F23` | |
1020
+ | `sdl.keyboard.SCANCODE.F24` | `SDL_SCANCODE_F24` | |
1021
+ | `sdl.keyboard.SCANCODE.EXECUTE` | `SDL_SCANCODE_EXECUTE` | |
1022
+ | `sdl.keyboard.SCANCODE.HELP` | `SDL_SCANCODE_HELP` | |
1023
+ | `sdl.keyboard.SCANCODE.MENU` | `SDL_SCANCODE_MENU` | |
1024
+ | `sdl.keyboard.SCANCODE.SELECT` | `SDL_SCANCODE_SELECT` | |
1025
+ | `sdl.keyboard.SCANCODE.STOP` | `SDL_SCANCODE_STOP` | |
1026
+ | `sdl.keyboard.SCANCODE.AGAIN` | `SDL_SCANCODE_AGAIN` | redo |
1027
+ | `sdl.keyboard.SCANCODE.UNDO` | `SDL_SCANCODE_UNDO` | |
1028
+ | `sdl.keyboard.SCANCODE.CUT` | `SDL_SCANCODE_CUT` | |
1029
+ | `sdl.keyboard.SCANCODE.COPY` | `SDL_SCANCODE_COPY` | |
1030
+ | `sdl.keyboard.SCANCODE.PASTE` | `SDL_SCANCODE_PASTE` | |
1031
+ | `sdl.keyboard.SCANCODE.FIND` | `SDL_SCANCODE_FIND` | |
1032
+ | `sdl.keyboard.SCANCODE.MUTE` | `SDL_SCANCODE_MUTE` | |
1033
+ | `sdl.keyboard.SCANCODE.VOLUMEUP` | `SDL_SCANCODE_VOLUMEUP` | |
1034
+ | `sdl.keyboard.SCANCODE.VOLUMEDOWN` | `SDL_SCANCODE_VOLUMEDOWN` | |
1035
+ | `sdl.keyboard.SCANCODE.KP_COMMA` | `SDL_SCANCODE_KP_COMMA` | |
1036
+ | `sdl.keyboard.SCANCODE.KP_EQUALSAS400` | `SDL_SCANCODE_KP_EQUALSAS400` | |
1037
+ | `sdl.keyboard.SCANCODE.INTERNATIONAL1` | `SDL_SCANCODE_INTERNATIONAL1` | used on Asian keyboards, see footnotes in USB doc |
1038
+ | `sdl.keyboard.SCANCODE.INTERNATIONAL2` | `SDL_SCANCODE_INTERNATIONAL2` | |
1039
+ | `sdl.keyboard.SCANCODE.INTERNATIONAL3` | `SDL_SCANCODE_INTERNATIONAL3` | Yen |
1040
+ | `sdl.keyboard.SCANCODE.INTERNATIONAL4` | `SDL_SCANCODE_INTERNATIONAL4` | |
1041
+ | `sdl.keyboard.SCANCODE.INTERNATIONAL5` | `SDL_SCANCODE_INTERNATIONAL5` | |
1042
+ | `sdl.keyboard.SCANCODE.INTERNATIONAL6` | `SDL_SCANCODE_INTERNATIONAL6` | |
1043
+ | `sdl.keyboard.SCANCODE.INTERNATIONAL7` | `SDL_SCANCODE_INTERNATIONAL7` | |
1044
+ | `sdl.keyboard.SCANCODE.INTERNATIONAL8` | `SDL_SCANCODE_INTERNATIONAL8` | |
1045
+ | `sdl.keyboard.SCANCODE.INTERNATIONAL9` | `SDL_SCANCODE_INTERNATIONAL9` | |
1046
+ | `sdl.keyboard.SCANCODE.LANG1` | `SDL_SCANCODE_LANG1` | Hangul/English toggle |
1047
+ | `sdl.keyboard.SCANCODE.LANG2` | `SDL_SCANCODE_LANG2` | Hanja conversion |
1048
+ | `sdl.keyboard.SCANCODE.LANG3` | `SDL_SCANCODE_LANG3` | Katakana |
1049
+ | `sdl.keyboard.SCANCODE.LANG4` | `SDL_SCANCODE_LANG4` | Hiragana |
1050
+ | `sdl.keyboard.SCANCODE.LANG5` | `SDL_SCANCODE_LANG5` | Zenkaku/Hankaku |
1051
+ | `sdl.keyboard.SCANCODE.LANG6` | `SDL_SCANCODE_LANG6` | |
1052
+ | `sdl.keyboard.SCANCODE.LANG7` | `SDL_SCANCODE_LANG7` | |
1053
+ | `sdl.keyboard.SCANCODE.LANG8` | `SDL_SCANCODE_LANG8` | |
1054
+ | `sdl.keyboard.SCANCODE.LANG9` | `SDL_SCANCODE_LANG9` | |
1055
+ | `sdl.keyboard.SCANCODE.ALTERASE` | `SDL_SCANCODE_ALTERASE` | Erase-Eaze |
1056
+ | `sdl.keyboard.SCANCODE.SYSREQ` | `SDL_SCANCODE_SYSREQ` | |
1057
+ | `sdl.keyboard.SCANCODE.CANCEL` | `SDL_SCANCODE_CANCEL` | |
1058
+ | `sdl.keyboard.SCANCODE.CLEAR` | `SDL_SCANCODE_CLEAR` | |
1059
+ | `sdl.keyboard.SCANCODE.PRIOR` | `SDL_SCANCODE_PRIOR` | |
1060
+ | `sdl.keyboard.SCANCODE.RETURN2` | `SDL_SCANCODE_RETURN2` | |
1061
+ | `sdl.keyboard.SCANCODE.SEPARATOR` | `SDL_SCANCODE_SEPARATOR` | |
1062
+ | `sdl.keyboard.SCANCODE.OUT` | `SDL_SCANCODE_OUT` | |
1063
+ | `sdl.keyboard.SCANCODE.OPER` | `SDL_SCANCODE_OPER` | |
1064
+ | `sdl.keyboard.SCANCODE.CLEARAGAIN` | `SDL_SCANCODE_CLEARAGAIN` | |
1065
+ | `sdl.keyboard.SCANCODE.CRSEL` | `SDL_SCANCODE_CRSEL` | |
1066
+ | `sdl.keyboard.SCANCODE.EXSEL` | `SDL_SCANCODE_EXSEL` | |
1067
+ | `sdl.keyboard.SCANCODE.KP_00` | `SDL_SCANCODE_KP_00` | |
1068
+ | `sdl.keyboard.SCANCODE.KP_000` | `SDL_SCANCODE_KP_000` | |
1069
+ | `sdl.keyboard.SCANCODE.THOUSANDSSEPARATOR` | `SDL_SCANCODE_THOUSANDSSEPARATOR` | |
1070
+ | `sdl.keyboard.SCANCODE.DECIMALSEPARATOR` | `SDL_SCANCODE_DECIMALSEPARATOR` | |
1071
+ | `sdl.keyboard.SCANCODE.CURRENCYUNIT` | `SDL_SCANCODE_CURRENCYUNIT` | |
1072
+ | `sdl.keyboard.SCANCODE.CURRENCYSUBUNIT` | `SDL_SCANCODE_CURRENCYSUBUNIT` | |
1073
+ | `sdl.keyboard.SCANCODE.KP_LEFTPAREN` | `SDL_SCANCODE_KP_LEFTPAREN` | |
1074
+ | `sdl.keyboard.SCANCODE.KP_RIGHTPAREN` | `SDL_SCANCODE_KP_RIGHTPAREN` | |
1075
+ | `sdl.keyboard.SCANCODE.KP_LEFTBRACE` | `SDL_SCANCODE_KP_LEFTBRACE` | |
1076
+ | `sdl.keyboard.SCANCODE.KP_RIGHTBRACE` | `SDL_SCANCODE_KP_RIGHTBRACE` | |
1077
+ | `sdl.keyboard.SCANCODE.KP_TAB` | `SDL_SCANCODE_KP_TAB` | |
1078
+ | `sdl.keyboard.SCANCODE.KP_BACKSPACE` | `SDL_SCANCODE_KP_BACKSPACE` | |
1079
+ | `sdl.keyboard.SCANCODE.KP_A` | `SDL_SCANCODE_KP_A` | |
1080
+ | `sdl.keyboard.SCANCODE.KP_B` | `SDL_SCANCODE_KP_B` | |
1081
+ | `sdl.keyboard.SCANCODE.KP_C` | `SDL_SCANCODE_KP_C` | |
1082
+ | `sdl.keyboard.SCANCODE.KP_D` | `SDL_SCANCODE_KP_D` | |
1083
+ | `sdl.keyboard.SCANCODE.KP_E` | `SDL_SCANCODE_KP_E` | |
1084
+ | `sdl.keyboard.SCANCODE.KP_F` | `SDL_SCANCODE_KP_F` | |
1085
+ | `sdl.keyboard.SCANCODE.KP_XOR` | `SDL_SCANCODE_KP_XOR` | |
1086
+ | `sdl.keyboard.SCANCODE.KP_POWER` | `SDL_SCANCODE_KP_POWER` | |
1087
+ | `sdl.keyboard.SCANCODE.KP_PERCENT` | `SDL_SCANCODE_KP_PERCENT` | |
1088
+ | `sdl.keyboard.SCANCODE.KP_LESS` | `SDL_SCANCODE_KP_LESS` | |
1089
+ | `sdl.keyboard.SCANCODE.KP_GREATER` | `SDL_SCANCODE_KP_GREATER` | |
1090
+ | `sdl.keyboard.SCANCODE.KP_AMPERSAND` | `SDL_SCANCODE_KP_AMPERSAND` | |
1091
+ | `sdl.keyboard.SCANCODE.KP_DBLAMPERSAND` | `SDL_SCANCODE_KP_DBLAMPERSAND` | |
1092
+ | `sdl.keyboard.SCANCODE.KP_VERTICALBAR` | `SDL_SCANCODE_KP_VERTICALBAR` | |
1093
+ | `sdl.keyboard.SCANCODE.KP_DBLVERTICALBAR` | `SDL_SCANCODE_KP_DBLVERTICALBAR` | |
1094
+ | `sdl.keyboard.SCANCODE.KP_COLON` | `SDL_SCANCODE_KP_COLON` | |
1095
+ | `sdl.keyboard.SCANCODE.KP_HASH` | `SDL_SCANCODE_KP_HASH` | |
1096
+ | `sdl.keyboard.SCANCODE.KP_SPACE` | `SDL_SCANCODE_KP_SPACE` | |
1097
+ | `sdl.keyboard.SCANCODE.KP_AT` | `SDL_SCANCODE_KP_AT` | |
1098
+ | `sdl.keyboard.SCANCODE.KP_EXCLAM` | `SDL_SCANCODE_KP_EXCLAM` | |
1099
+ | `sdl.keyboard.SCANCODE.KP_MEMSTORE` | `SDL_SCANCODE_KP_MEMSTORE` | |
1100
+ | `sdl.keyboard.SCANCODE.KP_MEMRECALL` | `SDL_SCANCODE_KP_MEMRECALL` | |
1101
+ | `sdl.keyboard.SCANCODE.KP_MEMCLEAR` | `SDL_SCANCODE_KP_MEMCLEAR` | |
1102
+ | `sdl.keyboard.SCANCODE.KP_MEMADD` | `SDL_SCANCODE_KP_MEMADD` | |
1103
+ | `sdl.keyboard.SCANCODE.KP_MEMSUBTRACT` | `SDL_SCANCODE_KP_MEMSUBTRACT` | |
1104
+ | `sdl.keyboard.SCANCODE.KP_MEMMULTIPLY` | `SDL_SCANCODE_KP_MEMMULTIPLY` | |
1105
+ | `sdl.keyboard.SCANCODE.KP_MEMDIVIDE` | `SDL_SCANCODE_KP_MEMDIVIDE` | |
1106
+ | `sdl.keyboard.SCANCODE.KP_PLUSMINUS` | `SDL_SCANCODE_KP_PLUSMINUS` | |
1107
+ | `sdl.keyboard.SCANCODE.KP_CLEAR` | `SDL_SCANCODE_KP_CLEAR` | |
1108
+ | `sdl.keyboard.SCANCODE.KP_CLEARENTRY` | `SDL_SCANCODE_KP_CLEARENTRY` | |
1109
+ | `sdl.keyboard.SCANCODE.KP_BINARY` | `SDL_SCANCODE_KP_BINARY` | |
1110
+ | `sdl.keyboard.SCANCODE.KP_OCTAL` | `SDL_SCANCODE_KP_OCTAL` | |
1111
+ | `sdl.keyboard.SCANCODE.KP_DECIMAL` | `SDL_SCANCODE_KP_DECIMAL` | |
1112
+ | `sdl.keyboard.SCANCODE.KP_HEXADECIMAL` | `SDL_SCANCODE_KP_HEXADECIMAL` | |
1113
+ | `sdl.keyboard.SCANCODE.LCTRL` | `SDL_SCANCODE_LCTRL` | |
1114
+ | `sdl.keyboard.SCANCODE.LSHIFT` | `SDL_SCANCODE_LSHIFT` | |
1115
+ | `sdl.keyboard.SCANCODE.LALT` | `SDL_SCANCODE_LALT` | alt, option |
1116
+ | `sdl.keyboard.SCANCODE.LGUI` | `SDL_SCANCODE_LGUI` | windows, command (apple), meta |
1117
+ | `sdl.keyboard.SCANCODE.RCTRL` | `SDL_SCANCODE_RCTRL` | |
1118
+ | `sdl.keyboard.SCANCODE.RSHIFT` | `SDL_SCANCODE_RSHIFT` | |
1119
+ | `sdl.keyboard.SCANCODE.RALT` | `SDL_SCANCODE_RALT` | alt gr, option |
1120
+ | `sdl.keyboard.SCANCODE.RGUI` | `SDL_SCANCODE_RGUI` | windows, command (apple), meta |
1121
+ | `sdl.keyboard.SCANCODE.MODE` | `SDL_SCANCODE_MODE` | |
1122
+ | `sdl.keyboard.SCANCODE.AUDIONEXT` | `SDL_SCANCODE_AUDIONEXT` | |
1123
+ | `sdl.keyboard.SCANCODE.AUDIOPREV` | `SDL_SCANCODE_AUDIOPREV` | |
1124
+ | `sdl.keyboard.SCANCODE.AUDIOSTOP` | `SDL_SCANCODE_AUDIOSTOP` | |
1125
+ | `sdl.keyboard.SCANCODE.AUDIOPLAY` | `SDL_SCANCODE_AUDIOPLAY` | |
1126
+ | `sdl.keyboard.SCANCODE.AUDIOMUTE` | `SDL_SCANCODE_AUDIOMUTE` | |
1127
+ | `sdl.keyboard.SCANCODE.MEDIASELECT` | `SDL_SCANCODE_MEDIASELECT` | |
1128
+ | `sdl.keyboard.SCANCODE.WWW` | `SDL_SCANCODE_WWW` | |
1129
+ | `sdl.keyboard.SCANCODE.MAIL` | `SDL_SCANCODE_MAIL` | |
1130
+ | `sdl.keyboard.SCANCODE.CALCULATOR` | `SDL_SCANCODE_CALCULATOR` | |
1131
+ | `sdl.keyboard.SCANCODE.COMPUTER` | `SDL_SCANCODE_COMPUTER` | |
1132
+ | `sdl.keyboard.SCANCODE.AC_SEARCH` | `SDL_SCANCODE_AC_SEARCH` | |
1133
+ | `sdl.keyboard.SCANCODE.AC_HOME` | `SDL_SCANCODE_AC_HOME` | |
1134
+ | `sdl.keyboard.SCANCODE.AC_BACK` | `SDL_SCANCODE_AC_BACK` | |
1135
+ | `sdl.keyboard.SCANCODE.AC_FORWARD` | `SDL_SCANCODE_AC_FORWARD` | |
1136
+ | `sdl.keyboard.SCANCODE.AC_STOP` | `SDL_SCANCODE_AC_STOP` | |
1137
+ | `sdl.keyboard.SCANCODE.AC_REFRESH` | `SDL_SCANCODE_AC_REFRESH` | |
1138
+ | `sdl.keyboard.SCANCODE.AC_BOOKMARKS` | `SDL_SCANCODE_AC_BOOKMARKS` | |
1139
+ | `sdl.keyboard.SCANCODE.BRIGHTNESSDOWN` | `SDL_SCANCODE_BRIGHTNESSDOWN` | |
1140
+ | `sdl.keyboard.SCANCODE.BRIGHTNESSUP` | `SDL_SCANCODE_BRIGHTNESSUP` | |
1141
+ | `sdl.keyboard.SCANCODE.DISPLAYSWITCH` | `SDL_SCANCODE_DISPLAYSWITCH` | display mirroring/dual display switch, video mode switch |
1142
+ | `sdl.keyboard.SCANCODE.KBDILLUMTOGGLE` | `SDL_SCANCODE_KBDILLUMTOGGLE` | |
1143
+ | `sdl.keyboard.SCANCODE.KBDILLUMDOWN` | `SDL_SCANCODE_KBDILLUMDOWN` | |
1144
+ | `sdl.keyboard.SCANCODE.KBDILLUMUP` | `SDL_SCANCODE_KBDILLUMUP` | |
1145
+ | `sdl.keyboard.SCANCODE.EJECT` | `SDL_SCANCODE_EJECT` | |
1146
+ | `sdl.keyboard.SCANCODE.SLEEP` | `SDL_SCANCODE_SLEEP` | |
1147
+ | `sdl.keyboard.SCANCODE.APP1` | `SDL_SCANCODE_APP1` | |
1148
+ | `sdl.keyboard.SCANCODE.APP2` | `SDL_SCANCODE_APP2` | |
1149
+ | `sdl.keyboard.SCANCODE.AUDIOREWIND` | `SDL_SCANCODE_AUDIOREWIND` | |
1150
+ | `sdl.keyboard.SCANCODE.AUDIOFASTFORWARD` | `SDL_SCANCODE_AUDIOFASTFORWARD` | |
1151
+ </details>
852
1152
 
853
- ### Sample formats
1153
+ ### Virtual keys
854
1154
 
855
- String values used to represent how audio samples are stored in a Buffer.
1155
+ String values used to represent virtual keys in the context of the current keyboard mapping.
1156
+ Note that some keys do not correspond to any virtual key.
1157
+ A Key can be either one of the values below __or__ any unicode character.
1158
+ Keys that produce characters are represented by that character.
1159
+ All others are represented by one of these values:
856
1160
 
857
- | Value | Corresponding `SDL_AudioFormat` | Comment |
858
- | --- | --- | --- |
859
- | `'s8'` | `AUDIO_S8` | signed 8-bit samples |
860
- | `'u8'` | `AUDIO_U8` | unsigned 8-bit samples |
861
- | `'s16lsb'` | `AUDIO_S16LSB` | signed 16-bit samples in little-endian byte order |
862
- | `'s16msb'` | `AUDIO_S16MSB` | signed 16-bit samples in big-endian byte order |
863
- | `'s16sys'` | `AUDIO_S16SYS` | signed 16-bit samples in native byte order |
864
- | `'s16'` | `AUDIO_S16` | alias for `'s16lsb'` |
865
- | `'u16lsb'` | `AUDIO_U16LSB` | unsigned 16-bit samples in little-endian byte order |
866
- | `'u16msb'` | `AUDIO_U16MSB` | unsigned 16-bit samples in big-endian byte order |
867
- | `'u16sys'` | `AUDIO_U16SYS` | unsigned 16-bit samples in native byte order |
868
- | `'u16'` | `AUDIO_U16` | alias for `'u16lsb'` |
869
- | `'s32lsb'` | `AUDIO_S32LSB` | 32-bit integer samples in little-endian byte order |
870
- | `'s32msb'` | `AUDIO_S32MSB` | 32-bit integer samples in big-endian byte order |
871
- | `'s32sys'` | `AUDIO_S32SYS` | 32-bit integer samples in native byte order |
872
- | `'s32'` | `AUDIO_S32` | alias for `'s32lsb'` |
873
- | `'f32lsb'` | `AUDIO_F32LSB` | 32-bit floating point samples in little-endian byte order |
874
- | `'f32msb'` | `AUDIO_F32MSB` | 32-bit floating point samples in big-endian byte order |
875
- | `'f32sys'` | `AUDIO_F32SYS` | 32-bit floating point samples in native byte order |
876
- | `'f32'` | `AUDIO_F32` | alias for `'f32lsb'` |
1161
+ `'&&'`, `'+/-'`, `'||'`, `'00'`, `'000'`, `'again'`, `'alt'`, `'altErase'`, `'app1'`, `'app2'`, `'application'`, `'audioFastForward'`, `'audioMute'`, `'audioNext'`, `'audioPlay'`, `'audioPrev'`, `'audioRewind'`, `'audioStop'`, `'back'`, `'backspace'`, `'binary'`, `'bookmarks'`, `'brightnessDown'`, `'brightnessUp'`, `'calculator'`, `'cancel'`, `'capsLock'`, `'clear'`, `'clearEntry'`, `'computer'`, `'copy'`, `'crSel'`, `'ctrl'`, `'currencySubUnit'`, `'currencyUnit'`, `'cut'`, `'decimal'`, `'decimalSeparator'`, `'delete'`, `'displaySwitch'`, `'down'`, `'eject'`, `'end'`, `'enter'`, `'escape'`, `'execute'`, `'exSel'`, `'f1'`, `'f2'`, `'f3'`, `'f4'`, `'f5'`, `'f6'`, `'f7'`, `'f8'`, `'f9'`, `'f10'`, `'f11'`, `'f12'`, `'f13'`, `'f14'`, `'f15'`, `'f16'`, `'f17'`, `'f18'`, `'f19'`, `'f20'`, `'f21'`, `'f22'`, `'f23'`, `'f24'`, `'find'`, `'forward'`, `'gui'`, `'help'`, `'hexadecimal'`, `'home'`, `'illumDown'`, `'illumToggle'`, `'illumUp'`, `'insert'`, `'left'`, `'mail'`, `'mediaSelect'`, `'memAdd'`, `'memClear'`, `'memDivide'`, `'memMultiply'`, `'memRecall'`, `'memStore'`, `'memSubtract'`, `'menu'`, `'modeSwitch'`, `'mute'`, `'numlock'`, `'octal'`, `'oper'`, `'out'`, `'pageDown'`, `'pageUp'`, `'paste'`, `'pause'`, `'power'`, `'printScreen'`, `'prior'`, `'refresh'`, `'return'`, `'right'`, `'scrollLock'`, `'search'`, `'select'`, `'separator'`, `'shift'`, `'sleep'`, `'space'`, `'stop'`, `'sysReq'`, `'tab'`, `'thousandsSeparator'`, `'undo'`, `'up'`, `'volumeDown'`, `'volumeUp'`, `'www'`, `'xor'`.
877
1162
 
878
- ### Event: 'deviceAdd'
1163
+ ### sdl.keyboard.getKey(scancode)
879
1164
 
880
- * `device: <object>`: An object from [`sdl.audio.devices`](#sdlaudioinstances) indicating the device that caused the event.
1165
+ * `scancode: `[`<Scancode>`](#enum-scancode)
1166
+ * Returns: [`<Key>`](#virtual-keys)`|<null>`
881
1167
 
882
- Fired when a new audio device becomes available.
883
- Check [`sdl.audio.devices`](#sdlaudioinstances) to get the new list of audio devices.
1168
+ Maps a scancode to the corresponding key based on the current keyboard mapping.
884
1169
 
885
- ### Event: 'deviceRemove'
1170
+ ### sdl.keyboard.getScancode(key)
886
1171
 
887
- * `device: <object>`: An object from [`sdl.audio.devices`](#sdlaudioinstances) indicating the device that caused the event.
1172
+ * `key: `[`<Key>`](#virtual-keys)
1173
+ * Returns: [`<Scancode>`](#enum-scancode)
888
1174
 
889
- Fired when an existing audio device is removed.
890
- Check [`sdl.audio.devices`](#sdlaudioinstances) to get the new list of audio devices.
891
- When this event is emitted, all instances that were opened from the removed device are closed automatically.
1175
+ Maps a key to the corresponding scancode based on the current keyboard mapping.
1176
+ If multiple physical keys produce the same virtual key, then only the first one will be returned.
892
1177
 
893
- ### sdl.audio.bytesPerSample(format)
1178
+ ### sdl.keyboard.getState()
894
1179
 
895
- * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
896
- * Returns: `<number>` The number of bytes.
1180
+ * Returns: `<boolean[]>` an object representing the state of each key.
897
1181
 
898
- Helper function which maps each sample format to the corresponding number of bytes its samples take up.
1182
+ The returned array can be indexed with [`Scancode`](#enum-scancode) values.
1183
+ The values will be `true` for keys that are pressed and `false` otherwise.
899
1184
 
900
- ### sdl.audio.minSampleValue(format)
901
1185
 
902
- * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
903
- * Returns: `<number>` The minimum sample value.
1186
+ ## sdl.mouse
904
1187
 
905
- Helper function which maps each sample format to the corresponding minimum value its samples can take.
1188
+ ### Mouse cursors
906
1189
 
907
- ### sdl.audio.maxSampleValue(format)
1190
+ String values used to represent the types of cursors available on most systems.
908
1191
 
909
- * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
910
- * Returns: `<number>` The maximum sample value.
1192
+ | Value | Corresponding `SDL_SystemCursor` | Description |
1193
+ | --- | --- | --- |
1194
+ | `'arrow'` | `SDL_SYSTEM_CURSOR_ARROW` | arrow |
1195
+ | `'ibeam'` | `SDL_SYSTEM_CURSOR_IBEAM` | i-beam |
1196
+ | `'wait'` | `SDL_SYSTEM_CURSOR_WAIT` | wait |
1197
+ | `'crosshair'` | `SDL_SYSTEM_CURSOR_CROSSHAIR` | crosshair |
1198
+ | `'waitarrow'` | `SDL_SYSTEM_CURSOR_WAITARROW` | small wait cursor (or wait if not available) |
1199
+ | `'sizenwse'` | `SDL_SYSTEM_CURSOR_SIZENWSE` | double arrow pointing northwest and southeast |
1200
+ | `'sizenesw'` | `SDL_SYSTEM_CURSOR_SIZENESW` | double arrow pointing northeast and southwest |
1201
+ | `'sizewe'` | `SDL_SYSTEM_CURSOR_SIZEWE` | double arrow pointing west and east |
1202
+ | `'sizens'` | `SDL_SYSTEM_CURSOR_SIZENS` | double arrow pointing north and south |
1203
+ | `'sizeall'` | `SDL_SYSTEM_CURSOR_SIZEALL` | four pointed arrow pointing north, south, east, and west |
1204
+ | `'no'` | `SDL_SYSTEM_CURSOR_NO` | slashed circle or crossbones |
1205
+ | `'hand'` | `SDL_SYSTEM_CURSOR_HAND` | hand |
911
1206
 
912
- Helper function which maps each sample format to the corresponding maximum value its samples can take.
1207
+ ### Enum: BUTTON
913
1208
 
914
- ### sdl.audio.zeroSampleValue(format)
1209
+ Used to represent the buttons on a mouse.
1210
+ A mouse can have many buttons, but the values for the three most common ones are represented in this enum.
915
1211
 
916
- * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
917
- * Returns: `<number>` The zero sample value.
1212
+ | Value | Corresponding `SDL_BUTTON_*` |
1213
+ | --- | --- |
1214
+ | `sdl.mouse.BUTTON.LEFT` | `SDL_BUTTON_LEFT` |
1215
+ | `sdl.mouse.BUTTON.MIDDLE` | `SDL_BUTTON_MIDDLE` |
1216
+ | `sdl.mouse.BUTTON.RIGHT` | `SDL_BUTTON_RIGHT` |
918
1217
 
919
- Helper function which maps each sample format to the sample value that corresponds to silence.
1218
+ ### sdl.mouse.getButton(button)
920
1219
 
921
- ### sdl.audio.readSample(format, buffer[, offset])
1220
+ * `button: <number>` The index of the button.
1221
+ * Returns: `<boolean>` Will be `true` if the button is pressed.
922
1222
 
923
- * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
924
- * `buffer: <Buffer>` The buffer to read the sample from.
925
- * `offset: <number>` The position from which to read the sample. Default: `0`
926
- * Returns: `<number>` The value of the sample read.
1223
+ Queries the state of a single mouse button.
927
1224
 
928
- Helper function which calls the appropriate `read*` method of `Buffer` based on the format argument.
929
- For example, a call to `sdl.audio.readSample('f32', buffer, offset)` would be equivalent to `buffer.readFloatLE(offset)`.
1225
+ ### sdl.mouse.position
930
1226
 
931
- ### sdl.audio.writeSample(format, buffer, value[, offset])
1227
+ * `<object>`
1228
+ * `x: <number>` The x position of the mouse, relative to the screen.
1229
+ * `y: <number>` The y position of the mouse, relative to the screen.
932
1230
 
933
- * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
934
- * `buffer: <Buffer>` The buffer to write the sample to.
935
- * `value: <number>` The value of the sample to write.
936
- * `offset: <number>` The position at which to write the sample. Default: `0`
937
- * Returns: `<number>` The updated `offset`.
1231
+ The position of the mouse on the screen.
938
1232
 
939
- Helper function which calls the appropriate `write*` method of `Buffer` based on the format argument.
940
- For example, a call to `sdl.audio.writeSample('f32', buffer, value, offset)` would be equivalent to `buffer.writeFloatLE(value, offset)`.
1233
+ ### sdl.mouse.setPosition(x, y)
941
1234
 
942
- ### sdl.audio.devices
1235
+ * `x: <number>` The new x position of the mouse, relative to the screen.
1236
+ * `y: <number>` The new y position of the mouse, relative to the screen.
943
1237
 
944
- * `<object>[]`
945
- * `name: <string>` The name of the device.
946
- * `recording: <boolean>` Will be `true` if this is a recording device.
1238
+ Moves the mouse to the specified position.
947
1239
 
948
- A list of all the detected audio devices.
949
- Sample output for PulseAudio:
1240
+ ### sdl.mouse.setCursor(cursor)
950
1241
 
951
- ```js
952
- [
953
- { name: 'Built-in Audio Analog Stereo', recording: false },
954
- { name: 'Built-in Audio Analog Stereo', recording: true }
955
- ]
956
- ```
1242
+ * `cursor: `[`<MouseCursor>`](#mouse-cursors) The icon to use for the cursor.
957
1243
 
958
- ### sdl.audio.openDevice(device[, options])
1244
+ Changes the icon that is displayed for the mouse cursor.
959
1245
 
960
- * `device: <object>` An object from [`sdl.audio.devices`](#sdlaudiodevices) that should be opened.
961
- * `options: <object>`
962
- * `name: <string>`: Some drivers accept custom names, such as a hostname/IP address for a remote audio server, or a filename in the diskaudio driver. Default: `device.name`.
963
- * `channels: <number>`: Number of audio channels. Valid values: `1`, `2`, `4`, `6`. Default `1`.
964
- * `frequency: <number>`: The sampling frequency in frames per second. Default `48e3`.
965
- * `format: `[`<SampleFormat>`](#sample-formats): The binary format for each sample. Default `'f32'`.
966
- * `buffered: <number>`: Number of frames that will be buffered by the driver. Must be a power of `2`. Default `4096`.
967
- * Returns: [`<AudioInstance>`](#class-audioinstance) an object representing the opened audio device instance.
1246
+ ### sdl.mouse.setCursorImage(width, height, stride, format, buffer, x, y)
968
1247
 
969
- Initializes an audio device for playback/recording and returns a corresponding instance.
970
- 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).
1248
+ * `width, height, stride, format, buffer: `[`<Image>`](#image-data) The image to use as a cursor.
1249
+ * `x: <number>` The x position of the cursor image's hotspot.
1250
+ * `y: <number>` The y position of the cursor image's hotspot.
971
1251
 
972
- 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.
973
- See also the section on [audio data](#audio-data).
1252
+ Sets a image to be the mouse cursor.
1253
+ The hotspot represents the pixel that is considered to be under the mouse.
974
1254
 
975
- The `buffered` option specifies the "delay" that you will experience between the application and the audio driver.
976
- With smaller values you will have smaller delays, but you will also have to read/write data from/to the driver more frequently.
977
- Applications such as virtual instruments that need to play audio in reaction to user input will want to change this option to lower values.
1255
+ ### sdl.mouse.showCursor([show])
978
1256
 
1257
+ * `show: <boolean>` If `true` then the mouse cursor will be visible.
1258
+ Default `true`.
979
1259
 
980
- ## class AudioInstance
1260
+ Changes the visibility of the mouse cursor.
981
1261
 
982
- This class is not directly exposed by the API so you can't use it with the `new` operator.
983
- It only serves as the base class for [`AudioPlaybackInstance`](#class-audioplaybackinstance-extends-audioinstance) and [`AudioRecordingInstance`](#class-audiorecordinginstance-extends-audioinstance).
1262
+ ### sdl.mouse.hideCursor()
984
1263
 
985
- ### audioInstance.id
1264
+ Equivalent to [`sdl.mouse.showCursor(false)`](#sdlmouseshowcursorshow).
1265
+
1266
+ ### sdl.mouse.capture([capture])
1267
+
1268
+ * `capture: <boolean>` If `true` the mouse will be captured by the current window.
1269
+ Default `true`.
1270
+
1271
+ When the mouse has been captured you will continue receiving mouse events even if the mouse is not over a window.
1272
+
1273
+ ### sdl.mouse.uncapture()
1274
+
1275
+ Equivalent to [`sdl.mouse.capture(false)`](#sdlmousecapturecapture).
1276
+
1277
+
1278
+ ## sdl.joystick
1279
+
1280
+ ### Joystick types
1281
+
1282
+ String values used to represent the type of a joystick device.
1283
+
1284
+ | Value | Corresponding `SDL_JoystickType` |
1285
+ | --- | --- |
1286
+ | `'unknown'` | `SDL_JOYSTICK_TYPE_UNKNOWN` |
1287
+ | `'gamecontroller'` | `SDL_JOYSTICK_TYPE_GAMECONTROLLER` |
1288
+ | `'wheel'` | `SDL_JOYSTICK_TYPE_WHEEL` |
1289
+ | `'arcadestick'` | `SDL_JOYSTICK_TYPE_ARCADE_STICK` |
1290
+ | `'flightstick'` | `SDL_JOYSTICK_TYPE_FLIGHT_STICK` |
1291
+ | `'dancepad'` | `SDL_JOYSTICK_TYPE_DANCE_PAD` |
1292
+ | `'guitar'` | `SDL_JOYSTICK_TYPE_GUITAR` |
1293
+ | `'drumkit'` | `SDL_JOYSTICK_TYPE_DRUM_KIT` |
1294
+ | `'arcadepad'` | `SDL_JOYSTICK_TYPE_ARCADE_PAD` |
1295
+ | `'throttle'` | `SDL_JOYSTICK_TYPE_THROTTLE` |
1296
+
1297
+ ### Hat positions
1298
+
1299
+ String values used to represent the positions of a joystick hat
1300
+
1301
+ | Value | Corresponding SDL enum |
1302
+ | --- | --- |
1303
+ | `'centered'` | `SDL_HAT_CENTERED` |
1304
+ | `'up'` | `SDL_HAT_UP` |
1305
+ | `'right'` | `SDL_HAT_RIGHT` |
1306
+ | `'down'` | `SDL_HAT_DOWN` |
1307
+ | `'left'` | `SDL_HAT_LEFT` |
1308
+ | `'rightup'` | `SDL_HAT_RIGHTUP` |
1309
+ | `'rightdown'` | `SDL_HAT_RIGHTDOWN` |
1310
+ | `'leftup'` | `SDL_HAT_LEFTUP` |
1311
+ | `'leftdown'` | `SDL_HAT_LEFTDOWN` |
1312
+
1313
+ ### Power levels
1314
+
1315
+ String values used to represent the power level of a joystick device.
1316
+
1317
+ | Value | Corresponding `SDL_JoystickPowerLevel` |
1318
+ | --- | --- |
1319
+ | `'unknown'` | `SDL_JOYSTICK_POWER_UNKNOWN` |
1320
+ | `'empty'` | `SDL_JOYSTICK_POWER_EMPTY` |
1321
+ | `'low'` | `SDL_JOYSTICK_POWER_LOW` |
1322
+ | `'medium'` | `SDL_JOYSTICK_POWER_MEDIUM` |
1323
+ | `'full'` | `SDL_JOYSTICK_POWER_FULL` |
1324
+ | `'wired'` | `SDL_JOYSTICK_POWER_WIRED` |
1325
+ | `'max'` | `SDL_JOYSTICK_POWER_MAX` |
1326
+
1327
+ <a id="joystick-event-device-add"></a>
1328
+
1329
+ ### Event: 'deviceAdd'
1330
+
1331
+ * `device: <object>`: An object from [`sdl.joystick.devices`](#sdljoystickdevices) indicating the device that caused the event.
1332
+
1333
+ Fired when a new joystick device becomes available.
1334
+ Check [`sdl.joystick.devices`](#sdljoystickdevices) to get the new list of joystick devices.
1335
+
1336
+ <a id="joystick-event-device-remove"></a>
1337
+
1338
+ ### Event: 'deviceRemove'
1339
+
1340
+ * `device: <object>`: An object from [`sdl.joystick.devices`](#sdljoystickdevices) indicating the device that caused the event.
1341
+
1342
+ Fired when an existing joystick device is removed.
1343
+ Check [`sdl.joystick.devices`](#sdljoystickdevices) to get the new list of joystick devices.
1344
+ When this event is emitted, all instances that were opened from the removed device are closed automatically.
1345
+
1346
+ ### sdl.joystick.devices
1347
+
1348
+ * `<object>[]`
1349
+ * `id: <number>` The unique id for the device.
1350
+ * `type:`[`<JoystickType>`](#joystick-types) The type of the device.
1351
+ * `name: <string>` The name of the device.
1352
+ * `path: <string>` The implementation dependent path of the device.
1353
+ * `guid: <string>` The GUID of the device.
1354
+ * `vendor: <number>` The USB vendor ID of the device.
1355
+ * `product: <number>` The USB product ID of the device.
1356
+ * `version: <number>` The USB product version of the device.
1357
+ * `player: <number>` The player index for the device.
1358
+
1359
+ A list of all the detected joystick devices.
1360
+ Sample output:
1361
+
1362
+ ```js
1363
+ [
1364
+ {
1365
+ id: 0,
1366
+ type: 'gamecontroller',
1367
+ name: 'DragonRise Inc. Generic USB Joystick',
1368
+ path: '/dev/input/event21',
1369
+ guid: '03000000790000000600000010010000',
1370
+ vendor: 121,
1371
+ product: 6,
1372
+ version: 272,
1373
+ player: 0,
1374
+ },
1375
+ ]
1376
+ ```
1377
+
1378
+ ### sdl.joystick.openDevice(device[, options])
1379
+
1380
+ * `device: <object>` An object from [`sdl.joystick.devices`](#sdljoystickdevices) that should be opened.
1381
+ * Returns: [`<joystickInstance>`](#class-joystickinstance) an object representing the opened joystick device instance.
1382
+
1383
+ Initializes a joystick device and returns a corresponding instance.
1384
+
1385
+ ## class JoystickInstance
1386
+
1387
+ This class is not directly exposed by the API so you can't use it with the `new` operator.
1388
+ Instead, objects returned by [`sdl.joystick.openDevice()`](#sdljoystickopendevicedevice) are of this type.
1389
+
1390
+ <a id="joystick-instance-event-axismotion"></a>
1391
+
1392
+ ### Event: 'axisMotion'
1393
+
1394
+ * `axis: <number>` The index of the axis that moved.
1395
+ * `value: <number>` The new axis position.
1396
+
1397
+ Fired when one of the joystick's axes moves.
1398
+
1399
+ ### Event: 'ballMotion'
1400
+
1401
+ * `ball: <number>` The index of the ball that moved.
1402
+ * `x: <number>` The new x-position of the ball.
1403
+ * `y: <number>` The new y-position of the ball.
1404
+
1405
+ Fired when one of the joystick's balls moves.
1406
+
1407
+ <a id="joystick-instance-event-buttondown"></a>
1408
+
1409
+ ### Event: 'buttonDown'
1410
+
1411
+ * `button: <number>` The index of the button that was pressed.
1412
+
1413
+ Fired when one of the joystick's buttons is pressed.
1414
+
1415
+ <a id="joystick-instance-event-buttonup"></a>
1416
+
1417
+ ### Event: 'buttonUp'
1418
+
1419
+ * `button: <number>` The index of the button that was released.
1420
+
1421
+ Fired when one of the joystick's buttons is released.
1422
+
1423
+ ### Event: 'hatMotion'
1424
+
1425
+ * `hat: <number>` The index of the hat that was moved.
1426
+ * `value: `[`<HatPosition>`](#hat-positions) The new hat position.
1427
+
1428
+ Fired when one of the joystick's hats is moved.
1429
+
1430
+ <a id="joystick-instance-event-close"></a>
1431
+
1432
+ ### Event: 'close'
1433
+
1434
+ Fired when the instance is about to close.
1435
+ Handle cleanup here.
1436
+
1437
+ ### joystickInstance.device
1438
+
1439
+ * `<object>`
1440
+
1441
+ The [device](#sdljoystickdevices) from which this instance was opened.
1442
+
1443
+ ### joystickInstance.firmwareVersion
1444
+
1445
+ * `<number>`
1446
+
1447
+ The joystick's firmware version.
1448
+
1449
+ ### joystickInstance.serialNumber
1450
+
1451
+ * `<string>|<null>`
1452
+
1453
+ The joystick's serial number, or `null` if it's not available.
1454
+
1455
+ ### joystickInstance.axes
1456
+
1457
+ * `<number>[]`
1458
+
1459
+ An array of values, each corresponding to the position of one of the joystick's axes.
1460
+ The values are normalized from `-1` to `+1`.
1461
+ It may be necessary to impose certain tolerances on these values to account for jitter.
1462
+
1463
+ ### joystickInstance.balls
1464
+
1465
+ * `<object>[]`
1466
+ * `x: <number>` The horizontal position of the joystick's ball.
1467
+ * `y: <number>` The vertical position of the joystick's ball.
1468
+
1469
+ An array of values, each corresponding to the position of one of the joystick's balls.
1470
+
1471
+ ### joystickInstance.buttons
1472
+
1473
+ * `<boolean>[]`
1474
+
1475
+ An array of values, each corresponding to the state of one of the joystick's buttons.
1476
+ The values will be `true` for buttons that are pressed and `false` otherwise.
1477
+
1478
+ ### joystickInstance.hats
1479
+
1480
+ * [`<HatPosition>`](#hat-positions)`[]`
1481
+
1482
+ An array of values, each corresponding to the position of one of the joystick's hats.
1483
+
1484
+ ### joystickInstance.power
1485
+
1486
+ * [`<PowerLevel>`](#power-levels)
1487
+
1488
+ The current power level of the joystick device.
1489
+
1490
+ ### joystickInstance.hasLed
1491
+
1492
+ * `<boolean>`
1493
+
1494
+ Will be `true` if there is a LED light on the joystick, whose color can be controlled.
1495
+
1496
+ ### joystickInstance.setLed(red, green, blue)
1497
+
1498
+ * `red: <number>` The red component of the led color, from `0` to `1`.
1499
+ * `green: <number>` The green component of the led color, from `0` to `1`.
1500
+ * `blue: <number>` The blue component of the led color, from `0` to `1`.
1501
+
1502
+ Sets the color of the LED light on the joystick.
1503
+
1504
+ ### joystickInstance.hasRumble
1505
+
1506
+ * `<boolean>`
1507
+
1508
+ Will be `true` if the joystick has rumble motors.
1509
+
1510
+ ### joystickInstance.rumble([low, [high, [duration]]])
1511
+
1512
+ * `low: <number>` The intensity of the low frequency rumble motor, from `0` to `1`. Default `1`.
1513
+ * `high: <number>` The intensity of the high frequency rumble motor, from `0` to `1`. Default `1`.
1514
+ * `duration: <number>` The duration of the rumble, in ms. Default `1e3`.
1515
+
1516
+ Makes the joystick rumble for a set `duration`.
1517
+ Calling this function again before `duration` has ran out, overrides the previous call.
1518
+
1519
+ ### joystickInstance.stopRumble()
1520
+
1521
+ Stops the joystick rumbling.
1522
+ Equivalent to `joystickInstance.rumble(0, 0)`.
1523
+
1524
+ ### joystickInstance.hasRumbleTriggers
1525
+
1526
+ * `<boolean>`
1527
+
1528
+ Will be `true` if the joystick has rumble motors on the triggers.
1529
+
1530
+ ### joystickInstance.rumbleTriggers([left, [right, [duration]]])
1531
+
1532
+ * `left: <number>` The intensity of the left trigger rumble motor, from `0` to `1`. Default `1`.
1533
+ * `right: <number>` The intensity of the right trigger rumble motor, from `0` to `1`. Default `1`.
1534
+ * `duration: <number>` The duration of the rumble, in ms. Default `1e3`.
1535
+
1536
+ Makes the joystick triggers rumble for a set `duration`.
1537
+ Calling this function again before `duration` has ran out, overrides the previous call.
1538
+
1539
+ ### joystickInstance.stopRumbleTriggers()
1540
+
1541
+ Stops the joystick trigger rumbling.
1542
+ Equivalent to `joystickInstance.rumbleTriggers(0, 0)`.
1543
+
1544
+ ### joystickInstance.closed
1545
+
1546
+ * `<boolean>`
1547
+
1548
+ Will be `true` if the instance is closed.
1549
+ A closed instance object should not be used any further.
1550
+
1551
+ ### joystickInstance.close()
1552
+
1553
+ Closes the instance.
1554
+
1555
+
1556
+ ## sdl.controller
1557
+
1558
+ An SDL controller is an abstraction over [`joysticks`](#sdljoystick) based on the xbox360 controller: They have a dpad, two analog sticks, 4 buttons on the right (called A, B, X, Y), shoulder buttons (two of which might be axes) and 3 buttons in the middle ("Start", "Back" and usually some kind of logo-button called "Guide").
1559
+ The SDL controller abstraction uses the naming-conventions of xbox360/XInput for all supported devices (for example devices that have a similar layout, like the Playstation DualShock Controller, but different button names), so you'll know that for example `controllerInstance.axes.leftStickX` is always the x-axis of the left analog stick, or `controllerInstance.buttons.b` is always the rightmost buttons of the 4 buttons on the right.
1560
+ This makes it easy to provide consistent input bindings, like "press B to jump, move around with the left analog stick".
1561
+ With a pure joystick instance it's impossible to know which axis or button corresponds to which physical axis/button on the device.
1562
+
1563
+ 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).
1564
+ For a joystick device to also be available as a controller device it needs a "mapping".
1565
+ A mapping is a string that consists of the device's name, it's GUID, and a series of pairings between one joystick axis/button and the corresponding controller axis/button name. See the sample output [`here`](#sdlcontrollerdevices) for an example.
1566
+ 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.
1567
+ You can add them via:
1568
+ ```js
1569
+ const url = 'https://raw.githubusercontent.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt'
1570
+ const result = await fetch(url)
1571
+ const text = await result.text()
1572
+ const mappings = text.split('\n')
1573
+ sdl.controller.addMappings(mappings)
1574
+ ```
1575
+
1576
+ ### Event: 'deviceAdd'
1577
+
1578
+ * `device: <object>`: An object from [`sdl.controller.devices`](#sdlcontrollerdevices) indicating the device that caused the event.
1579
+
1580
+ Fired when a new controller device becomes available.
1581
+ Check [`sdl.controller.devices`](#sdlcontrollerdevices) to get the new list of controller devices.
1582
+
1583
+ <a id="controller-event-device-remove"></a>
1584
+
1585
+ ### Event: 'deviceRemove'
1586
+
1587
+ * `device: <object>`: An object from [`sdl.controller.devices`](#sdlcontrollerdevices) indicating the device that caused the event.
1588
+
1589
+ Fired when an existing controller device is removed.
1590
+ Check [`sdl.controller.devices`](#sdlcontrollerdevices) to get the new list of controller devices.
1591
+ When this event is emitted, all instances that were opened from the removed device are closed automatically.
1592
+
1593
+ ### sdl.controller.addMappings(mappings)
1594
+
1595
+ * `mappings: <string>[]` An array of mappings to register.
1596
+
1597
+ Registers new mappings for controllers.
1598
+ This can cause already opened controller instances to be [remapped](#event-remap).
1599
+
1600
+ ### sdl.controller.devices
1601
+
1602
+ * `<object>[]`
1603
+ * `id: <number>` The unique id for the device.
1604
+ * `name: <string>` The name of the device.
1605
+ * `path: <string>` The implementation dependent path of the device.
1606
+ * `guid: <string>` The GUID of the device.
1607
+ * `vendor: <number>` The USB vendor ID of the device.
1608
+ * `product: <number>` The USB product ID of the device.
1609
+ * `version: <number>` The USB product version of the device.
1610
+ * `player: <number>` The player index for the device.
1611
+ * `mapping: <string>` The axis and button mapping for this device.
1612
+
1613
+ A list of all the detected controller devices.
1614
+ Sample output:
1615
+
1616
+ ```js
1617
+ [
1618
+ {
1619
+ id: 0,
1620
+ name: 'DragonRise Inc. Generic USB Joystick',
1621
+ path: '/dev/input/event21',
1622
+ guid: '03000000790000000600000010010000',
1623
+ vendor: 121,
1624
+ product: 6,
1625
+ version: 272,
1626
+ player: 0,
1627
+ mapping: '03000000790000000600000010010000,DragonRise Inc. Generic USB Joystick,a:b2,b:b1,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,leftshoulder:b4,leftstick:b10,lefttrigger:b6,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:b7,rightx:a3,righty:a4,start:b9,x:b3,y:b0,',
1628
+ },
1629
+ ]
1630
+ ```
1631
+
1632
+ ### sdl.controller.openDevice(device[, options])
1633
+
1634
+ * `device: <object>` An object from [`sdl.controller.devices`](#sdlcontrollerdevices) that should be opened.
1635
+ * Returns: [`<ControllerInstance>`](#class-controllerinstance) an object representing the opened controller device instance.
1636
+
1637
+ Initializes an controller device and returns a corresponding instance.
1638
+
1639
+ ## class ControllerInstance
1640
+
1641
+ This class is not directly exposed by the API so you can't use it with the `new` operator.
1642
+ Instead, objects returned by [`sdl.controller.openDevice()`](#sdlcontrolleropendevicedevice) are of this type.
1643
+
1644
+ <a id="controller-instance-event-axismotion"></a>
1645
+
1646
+ ### Event: 'axisMotion'
1647
+
1648
+ * `axis: <string>` The name of the axis that moved.
1649
+ * `value: <number>` The new axis position.
1650
+
1651
+ Fired when one of the controller's axes moves.
1652
+
1653
+ <a id="controller-instance-event-buttondown"></a>
1654
+
1655
+ ### Event: 'buttonDown'
1656
+
1657
+ * `button: <string>` The name of the button that was pressed.
1658
+
1659
+ Fired when one of the controller's buttons is pressed.
1660
+
1661
+ <a id="controller-instance-event-buttonup"></a>
1662
+
1663
+ ### Event: 'buttonUp'
1664
+
1665
+ * `button: <number>` The index of the button that was released.
1666
+
1667
+ Fired when one of the controller's buttons is released.
1668
+
1669
+ ### Event: 'remap'
1670
+
1671
+ Fired when a new mapping for this controller is applied (usually via [`sdl.controller.addMappings()`](#sdlcontrolleraddmappingsmappings)).
1672
+ This can cause all of the controller's axes and buttons to aquire new values.
1673
+
1674
+ <a id="controller-instance-event-close"></a>
1675
+
1676
+ ### Event: 'close'
1677
+
1678
+ Fired when the instance is about to close.
1679
+ Handle cleanup here.
1680
+
1681
+ ### controllerInstance.device
1682
+
1683
+ * `<object>`
1684
+
1685
+ The [device](#sdlcontrollerdevices) from which this instance was opened.
1686
+
1687
+ ### controllerInstance.firmwareVersion
1688
+
1689
+ * `<number>`
1690
+
1691
+ The controller's firmware version.
1692
+
1693
+ ### controllerInstance.serialNumber
1694
+
1695
+ * `<string>|<null>`
1696
+
1697
+ The controller's serial number, or `null` if it's not available.
1698
+
1699
+ ### controllerInstance.axes
1700
+
1701
+ * `<number>[]`
1702
+
1703
+ An array of values, each corresponding to the position of one of the controller's axes.
1704
+ The values are normalized from `-1` to `+1`.
1705
+ It may be necessary to impose certain tolerances on these values to account for jitter.
1706
+
1707
+ ### controllerInstance.buttons
1708
+
1709
+ * `<boolean>[]`
1710
+
1711
+ An array of values, each corresponding to the state of one of the controller's buttons.
1712
+ The values will be `true` for buttons that are pressed and `false` otherwise.
1713
+
1714
+ ### controllerInstance.power
1715
+
1716
+ * [`<PowerLevel>`](#power-levels)
1717
+
1718
+ The current power level of the controller device.
1719
+
1720
+ ### controllerInstance.hasLed
1721
+
1722
+ * `<boolean>`
1723
+
1724
+ Will be `true` if there is a LED light on the controller, whose color can be controlled.
1725
+
1726
+ ### controllerInstance.setLed(red, green, blue)
1727
+
1728
+ * `red: <number>` The red component of the led color, from `0` to `1`.
1729
+ * `green: <number>` The green component of the led color, from `0` to `1`.
1730
+ * `blue: <number>` The blue component of the led color, from `0` to `1`.
1731
+
1732
+ Sets the color of the LED light on the controller.
1733
+
1734
+ ### controllerInstance.hasRumble
1735
+
1736
+ * `<boolean>`
1737
+
1738
+ Will be `true` if the controller has rumble motors.
1739
+
1740
+ ### controllerInstance.rumble([low, [high, [duration]]])
1741
+
1742
+ * `low: <number>` The intensity of the low frequency rumble motor, from `0` to `1`. Default `1`.
1743
+ * `high: <number>` The intensity of the high frequency rumble motor, from `0` to `1`. Default `1`.
1744
+ * `duration: <number>` The duration of the rumble, in ms. Default `1e3`.
1745
+
1746
+ Makes the controller rumble for a set `duration`.
1747
+ Calling this function again before `duration` has ran out, overrides the previous call.
1748
+
1749
+ ### controllerInstance.stopRumble()
1750
+
1751
+ Stops the controller rumbling.
1752
+ Equivalent to `controllerInstance.rumble(0, 0)`.
1753
+
1754
+ ### controllerInstance.hasRumbleTriggers
1755
+
1756
+ * `<boolean>`
1757
+
1758
+ Will be `true` if the controller has rumble motors on the triggers.
1759
+
1760
+ ### controllerInstance.rumbleTriggers([left, [right, [duration]]])
1761
+
1762
+ * `left: <number>` The intensity of the left trigger rumble motor, from `0` to `1`. Default `1`.
1763
+ * `right: <number>` The intensity of the right trigger rumble motor, from `0` to `1`. Default `1`.
1764
+ * `duration: <number>` The duration of the rumble, in ms. Default `1e3`.
1765
+
1766
+ Makes the controller triggers rumble for a set `duration`.
1767
+ Calling this function again before `duration` has ran out, overrides the previous call.
1768
+
1769
+ ### controllerInstance.stopRumbleTriggers()
1770
+
1771
+ Stops the controller trigger rumbling.
1772
+ Equivalent to `controllerInstance.rumbleTriggers(0, 0)`.
1773
+
1774
+ ### controllerInstance.closed
1775
+
1776
+ * `<boolean>`
1777
+
1778
+ Will be `true` if the instance is closed.
1779
+ A closed instance object should not be used any further.
1780
+
1781
+ ### controllerInstance.close()
1782
+
1783
+ Closes the instance.
1784
+
1785
+ ## sdl.audio
1786
+
1787
+ ### Audio data
1788
+
1789
+ The [`playbackInstance.enqueue()`](#playbackinstanceenqueuebuffer-bytes) function expects a buffer of audio data as input and the [`recordingInstance.dequeue()`](#recordinginstancedequeuebuffer-bytes) function returns a buffer of audio data as output.
1790
+ The format of the data in these buffers depends on the options you passed to [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options).
1791
+
1792
+ An audio buffer is a sequence of frames, and each frame is a sequence of samples.
1793
+ A _sample_ is a single number representing the intensity of an audio channel at a point in time.
1794
+ For audio with multiple channels, each point in time is represented by multiple samples (one per channel) that together make up a _frame_.
1795
+ The samples in a frame are arranged as follows:
1796
+ * For 1 channel (mono) a frame contains just the one sample.
1797
+ * 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.
1798
+ * For 4 channels (quad) the layout is front-left, front-right, rear-left, rear-right.
1799
+ * For 6 channels (5.1) the layout is front-left, front-right, center, low-freq, rear-left, rear-right.
1800
+
1801
+ So for example, to fill a buffer with 3 seconds of a 440Hz sine wave, you could do:
1802
+
1803
+ ```js
1804
+ const TWO_PI = 2 * Math.PI
1805
+
1806
+ const {
1807
+ channels,
1808
+ frequency,
1809
+ bytesPerSample,
1810
+ minSampleValue,
1811
+ maxSampleValue,
1812
+ zeroSampleValue,
1813
+ } = playbackInstance
1814
+
1815
+ const range = maxSampleValue - minSampleValue
1816
+ const amplitude = range / 2
1817
+
1818
+ const sineAmplitude = 0.3 * amplitude
1819
+ const sineNote = 440
1820
+ const sinePeriod = 1 / sineNote
1821
+
1822
+ const duration = 3
1823
+ const numFrames = duration * frequency
1824
+ const numSamples = numFrames * channels
1825
+ const numBytes = numSamples * bytesPerSample
1826
+ const buffer = Buffer.alloc(numBytes)
1827
+
1828
+ let offset = 0
1829
+ for (let i = 0; i < numFrames; i++) {
1830
+ const time = i / frequency
1831
+ const angle = time / sinePeriod * TWO_PI
1832
+ const sample = zeroSampleValue + Math.sin(angle) * sineAmplitude
1833
+ for (let j = 0; j < channels; j++) {
1834
+ offset = playbackInstance.writeSample(buffer, sample, offset)
1835
+ }
1836
+ }
1837
+ ```
1838
+
1839
+ ### Sample formats
1840
+
1841
+ String values used to represent how audio samples are stored in a Buffer.
1842
+
1843
+ | Value | Corresponding `SDL_AudioFormat` | Comment |
1844
+ | --- | --- | --- |
1845
+ | `'s8'` | `AUDIO_S8` | signed 8-bit samples |
1846
+ | `'u8'` | `AUDIO_U8` | unsigned 8-bit samples |
1847
+ | `'s16lsb'` | `AUDIO_S16LSB` | signed 16-bit samples in little-endian byte order |
1848
+ | `'s16msb'` | `AUDIO_S16MSB` | signed 16-bit samples in big-endian byte order |
1849
+ | `'s16sys'` | `AUDIO_S16SYS` | signed 16-bit samples in native byte order |
1850
+ | `'s16'` | `AUDIO_S16` | alias for `'s16lsb'` |
1851
+ | `'u16lsb'` | `AUDIO_U16LSB` | unsigned 16-bit samples in little-endian byte order |
1852
+ | `'u16msb'` | `AUDIO_U16MSB` | unsigned 16-bit samples in big-endian byte order |
1853
+ | `'u16sys'` | `AUDIO_U16SYS` | unsigned 16-bit samples in native byte order |
1854
+ | `'u16'` | `AUDIO_U16` | alias for `'u16lsb'` |
1855
+ | `'s32lsb'` | `AUDIO_S32LSB` | 32-bit integer samples in little-endian byte order |
1856
+ | `'s32msb'` | `AUDIO_S32MSB` | 32-bit integer samples in big-endian byte order |
1857
+ | `'s32sys'` | `AUDIO_S32SYS` | 32-bit integer samples in native byte order |
1858
+ | `'s32'` | `AUDIO_S32` | alias for `'s32lsb'` |
1859
+ | `'f32lsb'` | `AUDIO_F32LSB` | 32-bit floating point samples in little-endian byte order |
1860
+ | `'f32msb'` | `AUDIO_F32MSB` | 32-bit floating point samples in big-endian byte order |
1861
+ | `'f32sys'` | `AUDIO_F32SYS` | 32-bit floating point samples in native byte order |
1862
+ | `'f32'` | `AUDIO_F32` | alias for `'f32lsb'` |
1863
+
1864
+ <a id="audio-event-device-add"></a>
1865
+
1866
+ ### Event: 'deviceAdd'
1867
+
1868
+ * `device: <object>`: An object from [`sdl.audio.devices`](#sdlaudiodevices) indicating the device that caused the event.
1869
+
1870
+ Fired when a new audio device becomes available.
1871
+ Check [`sdl.audio.devices`](#sdlaudiodevices) to get the new list of audio devices.
1872
+
1873
+ <a id="audio-event-device-remove"></a>
1874
+
1875
+ ### Event: 'deviceRemove'
1876
+
1877
+ * `device: <object>`: An object from [`sdl.audio.devices`](#sdlaudiodevices) indicating the device that caused the event.
1878
+
1879
+ Fired when an existing audio device is removed.
1880
+ Check [`sdl.audio.devices`](#sdlaudiodevices) to get the new list of audio devices.
1881
+ When this event is emitted, all instances that were opened from the removed device are closed automatically.
1882
+
1883
+ ### sdl.audio.bytesPerSample(format)
1884
+
1885
+ * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
1886
+ * Returns: `<number>` The number of bytes.
1887
+
1888
+ Helper function which maps each sample format to the corresponding number of bytes its samples take up.
1889
+
1890
+ ### sdl.audio.minSampleValue(format)
1891
+
1892
+ * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
1893
+ * Returns: `<number>` The minimum sample value.
1894
+
1895
+ Helper function which maps each sample format to the corresponding minimum value its samples can take.
1896
+
1897
+ ### sdl.audio.maxSampleValue(format)
1898
+
1899
+ * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
1900
+ * Returns: `<number>` The maximum sample value.
1901
+
1902
+ Helper function which maps each sample format to the corresponding maximum value its samples can take.
1903
+
1904
+ ### sdl.audio.zeroSampleValue(format)
1905
+
1906
+ * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
1907
+ * Returns: `<number>` The zero sample value.
1908
+
1909
+ Helper function which maps each sample format to the sample value that corresponds to silence.
1910
+
1911
+ ### sdl.audio.readSample(format, buffer[, offset])
1912
+
1913
+ * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
1914
+ * `buffer: <Buffer>` The buffer to read the sample from.
1915
+ * `offset: <number>` The position from which to read the sample. Default: `0`
1916
+ * Returns: `<number>` The value of the sample read.
1917
+
1918
+ Helper function which calls the appropriate `read*` method of `Buffer` based on the format argument.
1919
+ For example, a call to `sdl.audio.readSample('f32', buffer, offset)` would be equivalent to `buffer.readFloatLE(offset)`.
1920
+
1921
+ ### sdl.audio.readerName(format)
1922
+
1923
+ * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
1924
+ * Returns: `<string>` The name of the read method.
1925
+
1926
+ Helper function which returns the name of the appropriate `read*` method of `Buffer` based on the format argument.
1927
+ Most of the time you will want to use [sdl.audio.readSample](#sdlaudioreadsampleformat-buffer-offset) directly.
1928
+ The method name is only really useful for passing to worker threads.
1929
+
1930
+ ### sdl.audio.writeSample(format, buffer, value[, offset])
1931
+
1932
+ * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
1933
+ * `buffer: <Buffer>` The buffer to write the sample to.
1934
+ * `value: <number>` The value of the sample to write.
1935
+ * `offset: <number>` The position at which to write the sample. Default: `0`
1936
+ * Returns: `<number>` The updated `offset`.
1937
+
1938
+ Helper function which calls the appropriate `write*` method of `Buffer` based on the format argument.
1939
+ For example, a call to `sdl.audio.writeSample('f32', buffer, value, offset)` would be equivalent to `buffer.writeFloatLE(value, offset)`.
1940
+
1941
+ ### sdl.audio.writerName(format)
1942
+
1943
+ * `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
1944
+ * Returns: `<string>` The name of the write method.
1945
+
1946
+ Helper function which returns the name of the appropriate `write*` method of `Buffer` based on the format argument.
1947
+ Most of the time you will want to use [sdl.audio.writeSample](#sdlaudiowritesampleformat-buffer-value-offset) directly.
1948
+ The method name is only really useful for passing to worker threads.
1949
+
1950
+ ### sdl.audio.devices
1951
+
1952
+ * `<object>[]`
1953
+ * `type: <string>` Will be either `'playback'` or `'recording'`.
1954
+ * `name: <string>` The name of the device.
1955
+
1956
+ A list of all the detected audio devices.
1957
+ Sample output for PulseAudio:
1958
+
1959
+ ```js
1960
+ [
1961
+ { name: 'Built-in Audio Analog Stereo', type: 'playback' },
1962
+ { name: 'Built-in Audio Analog Stereo', type: 'recording' },
1963
+ ]
1964
+ ```
1965
+
1966
+ Note that this list can sometimes be empty.
1967
+ 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:
1968
+
1969
+ ```js
1970
+ const playbackInstance = sdl.audio.openDevice({ type: 'playback' })
1971
+ ```
1972
+
1973
+ ### sdl.audio.openDevice(device[, options])
1974
+
1975
+ * `device: <object>` An object from [`sdl.audio.devices`](#sdlaudiodevices), or a custom device.
1976
+ * `type: <string>`: Should be either `'playback'` or `'recording'`.
1977
+ * `name: <string>|<null>`: The name of the device. Optional.
1978
+ * `options: <object>`
1979
+ * `channels: <number>`: Number of audio channels. Valid values: `1`, `2`, `4`, `6`. Default `1`.
1980
+ * `frequency: <number>`: The sampling frequency in frames per second. Default `48e3`.
1981
+ * `format: `[`<SampleFormat>`](#sample-formats): The binary format for each sample. Default `'f32'`.
1982
+ * `buffered: <number>`: Number of frames that will be buffered by the driver. Must be a power of `2`. Default `4096`.
1983
+ * Returns: [`<AudioInstance>`](#class-audioinstance) an object representing the opened audio device instance.
1984
+
1985
+ Initializes an audio device for playback/recording and returns a corresponding instance.
1986
+ 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).
1987
+
1988
+ Most of the time you will be passing objects from [`sdl.audio.devices`](#sdlaudiodevices) as the first argument to this function.
1989
+ It is also possible to let SDL pick the most appropriate device by only passing the `type` property without a `name` like this:
1990
+
1991
+ ```js
1992
+ const playbackInstance = sdl.audio.openDevice({ type: 'playback' })
1993
+ ```
1994
+
1995
+ 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.
1996
+ These drivers will usually return an empty list for [`sdl.audio.devices`](#sdlaudiodevices).
1997
+
1998
+ 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.
1999
+ See also the section on [audio data](#audio-data).
2000
+
2001
+ The `buffered` option specifies the "delay" that you will experience between the application and the audio driver.
2002
+ With smaller values you will have smaller delays, but you will also have to read/write data from/to the driver more frequently.
2003
+ Applications such as virtual instruments that need to play audio in reaction to user input will want to change this option to lower values.
2004
+
2005
+
2006
+ ## class AudioInstance
2007
+
2008
+ This class is not directly exposed by the API so you can't use it with the `new` operator.
2009
+ It only serves as the base class for [`AudioPlaybackInstance`](#class-audioplaybackinstance-extends-audioinstance) and [`AudioRecordingInstance`](#class-audiorecordinginstance-extends-audioinstance).
2010
+
2011
+ <a id="audio-instance-event-close"></a>
2012
+
2013
+ ### Event: 'close'
2014
+
2015
+ Fired when the audio instance is about to close.
2016
+ Handle cleanup here.
2017
+
2018
+ ### audioInstance.id
986
2019
 
987
2020
  * `<number>`
988
2021
 
@@ -992,13 +2025,7 @@ A unique identifier for the instance.
992
2025
 
993
2026
  * `<object>`
994
2027
 
995
- The [device](#sdlaudiodevices) from which this instance was opened.
996
-
997
- ### audioInstance.name
998
-
999
- * `<string>`
1000
-
1001
- The name the instance was opened with.
2028
+ The device passed to [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) when this instance was opened.
1002
2029
 
1003
2030
  ### audioInstance.channels
1004
2031
 
@@ -1051,6 +2078,14 @@ The sample value that corresponds to silence, based on the format the instance w
1051
2078
  Helper function which calls the appropriate `read*` method of `Buffer` based on the format the instance was opened with.
1052
2079
  For example, for an instance opened with the `'f32'` sample format, a call to `audioinstance.readSample(buffer, offset)` would be equivalent to `buffer.readFloatLE(offset)`.
1053
2080
 
2081
+ ### audioInstance.readerName
2082
+
2083
+ * `<string>`
2084
+
2085
+ The name of the appropriate `read*` method of `Buffer` based on the format the instance was opened with.
2086
+ Most of the time you will want to use [audioInstance.readSample](#audioinstancereadsamplebuffer-offset) directly.
2087
+ The method name is only really useful for passing to worker threads.
2088
+
1054
2089
  ### audioInstance.writeSample(buffer, value[, offset])
1055
2090
 
1056
2091
  * `buffer: <Buffer>` The buffer to write the sample to.
@@ -1061,6 +2096,14 @@ For example, for an instance opened with the `'f32'` sample format, a call to `a
1061
2096
  Helper function which calls the appropriate `write*` method of `Buffer` based on the format the instance was opened with.
1062
2097
  For example, for an instance opened with the `'f32'` sample format, a call to `audioinstance.writeSample(buffer, value, offset)` would be equivalent to `buffer.writeFloatLE(value, offset)`.
1063
2098
 
2099
+ ### audioInstance.writerName
2100
+
2101
+ * `<string>`
2102
+
2103
+ The name of the appropriate `write*` method of `Buffer` based on the format the instance was opened with.
2104
+ Most of the time you will want to use [audioInstance.writeSample](#audioinstancewritesamplebuffer-value-offset) directly.
2105
+ The method name is only really useful for passing to worker threads.
2106
+
1064
2107
  ### audioInstance.buffered
1065
2108
 
1066
2109
  * `<number>`
@@ -1132,408 +2175,6 @@ Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevic
1132
2175
  Takes recorded audio data that has been put on the queue, and writes it to the provided buffer.
1133
2176
 
1134
2177
 
1135
- ## sdl.keyboard
1136
-
1137
- There are three levels at which you can deal with the keyboard: physical keys ([scancodes](#enum-scancode)), virtual keys ([keys](#virtual-keys)), and text ([`'textInput'`](#event-textinput) events).
1138
-
1139
- On the physical level, each of the physical keys corresponds to a number: the key's scancode.
1140
- For any given keyboard, the same key will always produce the same scancode.
1141
- If your application cares about the layout of the keyboard (for example using the "WASD" keys as a substitute for arrow keys), then you should handle key events at this level using the `scancode` property of [`'keyDown'`](#event-keydown) and [`'keyUp'`](#event-keyup) events.
1142
-
1143
- 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.
1144
-
1145
- 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.).
1146
- Your operating system provides a "keyboard mapping" that associates physical keys with their corresponding meaning.
1147
- 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).
1148
- These meanings are represented as [virtual key strings](#virtual-keys).
1149
- If your application cares about the meaning associated with individual keys then you should handle key events at this level using the `key` property of [`'keyDown'`](#event-keydown) and [`'keyUp'`](#event-keyup) events.
1150
-
1151
- Note that not all physical keys correspond to a well-defined meaning and thus don't have a virtual key value associated with them.
1152
- The key events for these keys will have a `null` value for the `key` property.
1153
-
1154
- But sometimes the application doesn't care about individual keys at all, but about the resulting text that the user is entering.
1155
- Consider for example what happens when a user on a Greek keyboard layout enters an accent mark "´" followed by the letter "α" to produce the character "ά": Two keys were pressed, but only a single character was produced.
1156
- Trying to handle text input by manually translating key presses to text is not a very viable solution.
1157
- It's better to let the OS handle all the text logic, and get the final text by handling the rasulting ([`'textInput'`](#event-textinput)) events.
1158
-
1159
-
1160
- ### Enum: SCANCODE
1161
-
1162
- Used to represent physical keys on the keyboard.
1163
- The same key will always produce the same scancode.
1164
- Values are based on the [USB usage page standard](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf).
1165
-
1166
- | Value | Corresponding `SDL_Scancode` | Comment |
1167
- | --- | --- | --- |
1168
- | `sdl.keyboard.SCANCODE.UNKNOWN` | `SDL_SCANCODE_UNKNOWN` | value `0` |
1169
- | `sdl.keyboard.SCANCODE.A` | `SDL_SCANCODE_A` | |
1170
- | `sdl.keyboard.SCANCODE.B` | `SDL_SCANCODE_B` | |
1171
- | `sdl.keyboard.SCANCODE.C` | `SDL_SCANCODE_C` | |
1172
- | `sdl.keyboard.SCANCODE.D` | `SDL_SCANCODE_D` | |
1173
- | `sdl.keyboard.SCANCODE.E` | `SDL_SCANCODE_E` | |
1174
- | `sdl.keyboard.SCANCODE.F` | `SDL_SCANCODE_F` | |
1175
- | `sdl.keyboard.SCANCODE.G` | `SDL_SCANCODE_G` | |
1176
- | `sdl.keyboard.SCANCODE.H` | `SDL_SCANCODE_H` | |
1177
- | `sdl.keyboard.SCANCODE.I` | `SDL_SCANCODE_I` | |
1178
- | `sdl.keyboard.SCANCODE.J` | `SDL_SCANCODE_J` | |
1179
- | `sdl.keyboard.SCANCODE.K` | `SDL_SCANCODE_K` | |
1180
- | `sdl.keyboard.SCANCODE.L` | `SDL_SCANCODE_L` | |
1181
- | `sdl.keyboard.SCANCODE.M` | `SDL_SCANCODE_M` | |
1182
- | `sdl.keyboard.SCANCODE.N` | `SDL_SCANCODE_N` | |
1183
- | `sdl.keyboard.SCANCODE.O` | `SDL_SCANCODE_O` | |
1184
- | `sdl.keyboard.SCANCODE.P` | `SDL_SCANCODE_P` | |
1185
- | `sdl.keyboard.SCANCODE.Q` | `SDL_SCANCODE_Q` | |
1186
- | `sdl.keyboard.SCANCODE.R` | `SDL_SCANCODE_R` | |
1187
- | `sdl.keyboard.SCANCODE.S` | `SDL_SCANCODE_S` | |
1188
- | `sdl.keyboard.SCANCODE.T` | `SDL_SCANCODE_T` | |
1189
- | `sdl.keyboard.SCANCODE.U` | `SDL_SCANCODE_U` | |
1190
- | `sdl.keyboard.SCANCODE.V` | `SDL_SCANCODE_V` | |
1191
- | `sdl.keyboard.SCANCODE.W` | `SDL_SCANCODE_W` | |
1192
- | `sdl.keyboard.SCANCODE.X` | `SDL_SCANCODE_X` | |
1193
- | `sdl.keyboard.SCANCODE.Y` | `SDL_SCANCODE_Y` | |
1194
- | `sdl.keyboard.SCANCODE.Z` | `SDL_SCANCODE_Z` | |
1195
- | `sdl.keyboard.SCANCODE.1` | `SDL_SCANCODE_1` | |
1196
- | `sdl.keyboard.SCANCODE.2` | `SDL_SCANCODE_2` | |
1197
- | `sdl.keyboard.SCANCODE.3` | `SDL_SCANCODE_3` | |
1198
- | `sdl.keyboard.SCANCODE.4` | `SDL_SCANCODE_4` | |
1199
- | `sdl.keyboard.SCANCODE.5` | `SDL_SCANCODE_5` | |
1200
- | `sdl.keyboard.SCANCODE.6` | `SDL_SCANCODE_6` | |
1201
- | `sdl.keyboard.SCANCODE.7` | `SDL_SCANCODE_7` | |
1202
- | `sdl.keyboard.SCANCODE.8` | `SDL_SCANCODE_8` | |
1203
- | `sdl.keyboard.SCANCODE.9` | `SDL_SCANCODE_9` | |
1204
- | `sdl.keyboard.SCANCODE.0` | `SDL_SCANCODE_0` | |
1205
- | `sdl.keyboard.SCANCODE.RETURN` | `SDL_SCANCODE_RETURN` | |
1206
- | `sdl.keyboard.SCANCODE.ESCAPE` | `SDL_SCANCODE_ESCAPE` | |
1207
- | `sdl.keyboard.SCANCODE.BACKSPACE` | `SDL_SCANCODE_BACKSPACE` | |
1208
- | `sdl.keyboard.SCANCODE.TAB` | `SDL_SCANCODE_TAB` | |
1209
- | `sdl.keyboard.SCANCODE.SPACE` | `SDL_SCANCODE_SPACE` | |
1210
- | `sdl.keyboard.SCANCODE.MINUS` | `SDL_SCANCODE_MINUS` | |
1211
- | `sdl.keyboard.SCANCODE.EQUALS` | `SDL_SCANCODE_EQUALS` | |
1212
- | `sdl.keyboard.SCANCODE.LEFTBRACKET` | `SDL_SCANCODE_LEFTBRACKET` | |
1213
- | `sdl.keyboard.SCANCODE.RIGHTBRACKET` | `SDL_SCANCODE_RIGHTBRACKET` | |
1214
- | `sdl.keyboard.SCANCODE.BACKSLASH` | `SDL_SCANCODE_BACKSLASH` | Located at the lower left of the return key on ISO keyboards and at the right end of the QWERTY row on ANSI keyboards. Produces REVERSE SOLIDUS (backslash) and VERTICAL LINE in a US layout, REVERSE SOLIDUS and VERTICAL LINE in a UK Mac layout, NUMBER SIGN and TILDE in a UK Windows layout, DOLLAR SIGN and POUND SIGN in a Swiss German layout, NUMBER SIGN and APOSTROPHE in a German layout, GRAVE ACCENT and POUND SIGN in a French Mac layout, and ASTERISK and MICRO SIGN in a French Windows layout. |
1215
- | `sdl.keyboard.SCANCODE.NONUSHASH` | `SDL_SCANCODE_NONUSHASH` | ISO USB keyboards actually use this code instead of 49 for the same key, but all OSes I've seen treat the two codes identically. So, as an implementor, unless your keyboard generates both of those codes and your OS treats them differently, you should generate SDL_SCANCODE_BACKSLASH instead of this code. As a user, you should not rely on this code because SDL will never generate it with most (all?) keyboards. |
1216
- | `sdl.keyboard.SCANCODE.SEMICOLON` | `SDL_SCANCODE_SEMICOLON` | |
1217
- | `sdl.keyboard.SCANCODE.APOSTROPHE` | `SDL_SCANCODE_APOSTROPHE` | |
1218
- | `sdl.keyboard.SCANCODE.GRAVE` | `SDL_SCANCODE_GRAVE` | Located in the top left corner (on both ANSI and ISO keyboards). Produces GRAVE ACCENT and TILDE in a US Windows layout and in US and UK Mac layouts on ANSI keyboards, GRAVE ACCENT and NOT SIGN in a UK Windows layout, SECTION SIGN and PLUS-MINUS SIGN in US and UK Mac layouts on ISO keyboards, SECTION SIGN and DEGREE SIGN in a Swiss German layout (Mac: only on ISO keyboards), CIRCUMFLEX ACCENT and DEGREE SIGN in a German layout (Mac: only on ISO keyboards), SUPERSCRIPT TWO and TILDE in a French Windows layout, COMMERCIAL AT and NUMBER SIGN in a French Mac layout on ISO keyboards, and LESS-THAN SIGN and GREATER-THAN SIGN in a Swiss German, German, or French Mac layout on ANSI keyboards. |
1219
- | `sdl.keyboard.SCANCODE.COMMA` | `SDL_SCANCODE_COMMA` | |
1220
- | `sdl.keyboard.SCANCODE.PERIOD` | `SDL_SCANCODE_PERIOD` | |
1221
- | `sdl.keyboard.SCANCODE.SLASH` | `SDL_SCANCODE_SLASH` | |
1222
- | `sdl.keyboard.SCANCODE.CAPSLOCK` | `SDL_SCANCODE_CAPSLOCK` | |
1223
- | `sdl.keyboard.SCANCODE.F1` | `SDL_SCANCODE_F1` | |
1224
- | `sdl.keyboard.SCANCODE.F2` | `SDL_SCANCODE_F2` | |
1225
- | `sdl.keyboard.SCANCODE.F3` | `SDL_SCANCODE_F3` | |
1226
- | `sdl.keyboard.SCANCODE.F4` | `SDL_SCANCODE_F4` | |
1227
- | `sdl.keyboard.SCANCODE.F5` | `SDL_SCANCODE_F5` | |
1228
- | `sdl.keyboard.SCANCODE.F6` | `SDL_SCANCODE_F6` | |
1229
- | `sdl.keyboard.SCANCODE.F7` | `SDL_SCANCODE_F7` | |
1230
- | `sdl.keyboard.SCANCODE.F8` | `SDL_SCANCODE_F8` | |
1231
- | `sdl.keyboard.SCANCODE.F9` | `SDL_SCANCODE_F9` | |
1232
- | `sdl.keyboard.SCANCODE.F10` | `SDL_SCANCODE_F10` | |
1233
- | `sdl.keyboard.SCANCODE.F11` | `SDL_SCANCODE_F11` | |
1234
- | `sdl.keyboard.SCANCODE.F12` | `SDL_SCANCODE_F12` | |
1235
- | `sdl.keyboard.SCANCODE.PRINTSCREEN` | `SDL_SCANCODE_PRINTSCREEN` | |
1236
- | `sdl.keyboard.SCANCODE.SCROLLLOCK` | `SDL_SCANCODE_SCROLLLOCK` | |
1237
- | `sdl.keyboard.SCANCODE.PAUSE` | `SDL_SCANCODE_PAUSE` | |
1238
- | `sdl.keyboard.SCANCODE.INSERT` | `SDL_SCANCODE_INSERT` | insert on PC, help on some Mac keyboards |
1239
- | `sdl.keyboard.SCANCODE.HOME` | `SDL_SCANCODE_HOME` | |
1240
- | `sdl.keyboard.SCANCODE.PAGEUP` | `SDL_SCANCODE_PAGEUP` | |
1241
- | `sdl.keyboard.SCANCODE.DELETE` | `SDL_SCANCODE_DELETE` | |
1242
- | `sdl.keyboard.SCANCODE.END` | `SDL_SCANCODE_END` | |
1243
- | `sdl.keyboard.SCANCODE.PAGEDOWN` | `SDL_SCANCODE_PAGEDOWN` | |
1244
- | `sdl.keyboard.SCANCODE.RIGHT` | `SDL_SCANCODE_RIGHT` | |
1245
- | `sdl.keyboard.SCANCODE.LEFT` | `SDL_SCANCODE_LEFT` | |
1246
- | `sdl.keyboard.SCANCODE.DOWN` | `SDL_SCANCODE_DOWN` | |
1247
- | `sdl.keyboard.SCANCODE.UP` | `SDL_SCANCODE_UP` | |
1248
- | `sdl.keyboard.SCANCODE.NUMLOCKCLEAR` | `SDL_SCANCODE_NUMLOCKCLEAR` | num lock on PC, clear on Mac keyboards |
1249
- | `sdl.keyboard.SCANCODE.KP_DIVIDE` | `SDL_SCANCODE_KP_DIVIDE` | |
1250
- | `sdl.keyboard.SCANCODE.KP_MULTIPLY` | `SDL_SCANCODE_KP_MULTIPLY` | |
1251
- | `sdl.keyboard.SCANCODE.KP_MINUS` | `SDL_SCANCODE_KP_MINUS` | |
1252
- | `sdl.keyboard.SCANCODE.KP_PLUS` | `SDL_SCANCODE_KP_PLUS` | |
1253
- | `sdl.keyboard.SCANCODE.KP_ENTER` | `SDL_SCANCODE_KP_ENTER` | |
1254
- | `sdl.keyboard.SCANCODE.KP_1` | `SDL_SCANCODE_KP_1` | |
1255
- | `sdl.keyboard.SCANCODE.KP_2` | `SDL_SCANCODE_KP_2` | |
1256
- | `sdl.keyboard.SCANCODE.KP_3` | `SDL_SCANCODE_KP_3` | |
1257
- | `sdl.keyboard.SCANCODE.KP_4` | `SDL_SCANCODE_KP_4` | |
1258
- | `sdl.keyboard.SCANCODE.KP_5` | `SDL_SCANCODE_KP_5` | |
1259
- | `sdl.keyboard.SCANCODE.KP_6` | `SDL_SCANCODE_KP_6` | |
1260
- | `sdl.keyboard.SCANCODE.KP_7` | `SDL_SCANCODE_KP_7` | |
1261
- | `sdl.keyboard.SCANCODE.KP_8` | `SDL_SCANCODE_KP_8` | |
1262
- | `sdl.keyboard.SCANCODE.KP_9` | `SDL_SCANCODE_KP_9` | |
1263
- | `sdl.keyboard.SCANCODE.KP_0` | `SDL_SCANCODE_KP_0` | |
1264
- | `sdl.keyboard.SCANCODE.KP_PERIOD` | `SDL_SCANCODE_KP_PERIOD` | |
1265
- | `sdl.keyboard.SCANCODE.NONUSBACKSLASH` | `SDL_SCANCODE_NONUSBACKSLASH` | This is the additional key that ISO keyboards have over ANSI ones, located between left shift and Y. Produces GRAVE ACCENT and TILDE in a US or UK Mac layout, REVERSE SOLIDUS (backslash) and VERTICAL LINE in a US or UK Windows layout, and LESS-THAN SIGN and GREATER-THAN SIGN in a Swiss German, German, or French layout. |
1266
- | `sdl.keyboard.SCANCODE.APPLICATION` | `SDL_SCANCODE_APPLICATION` | windows contextual menu, compose |
1267
- | `sdl.keyboard.SCANCODE.POWER` | `SDL_SCANCODE_POWER` | The USB document says this is a status flag, not a physical key - but some Mac keyboards do have a power key. |
1268
- | `sdl.keyboard.SCANCODE.KP_EQUALS` | `SDL_SCANCODE_KP_EQUALS` | |
1269
- | `sdl.keyboard.SCANCODE.F13` | `SDL_SCANCODE_F13` | |
1270
- | `sdl.keyboard.SCANCODE.F14` | `SDL_SCANCODE_F14` | |
1271
- | `sdl.keyboard.SCANCODE.F15` | `SDL_SCANCODE_F15` | |
1272
- | `sdl.keyboard.SCANCODE.F16` | `SDL_SCANCODE_F16` | |
1273
- | `sdl.keyboard.SCANCODE.F17` | `SDL_SCANCODE_F17` | |
1274
- | `sdl.keyboard.SCANCODE.F18` | `SDL_SCANCODE_F18` | |
1275
- | `sdl.keyboard.SCANCODE.F19` | `SDL_SCANCODE_F19` | |
1276
- | `sdl.keyboard.SCANCODE.F20` | `SDL_SCANCODE_F20` | |
1277
- | `sdl.keyboard.SCANCODE.F21` | `SDL_SCANCODE_F21` | |
1278
- | `sdl.keyboard.SCANCODE.F22` | `SDL_SCANCODE_F22` | |
1279
- | `sdl.keyboard.SCANCODE.F23` | `SDL_SCANCODE_F23` | |
1280
- | `sdl.keyboard.SCANCODE.F24` | `SDL_SCANCODE_F24` | |
1281
- | `sdl.keyboard.SCANCODE.EXECUTE` | `SDL_SCANCODE_EXECUTE` | |
1282
- | `sdl.keyboard.SCANCODE.HELP` | `SDL_SCANCODE_HELP` | |
1283
- | `sdl.keyboard.SCANCODE.MENU` | `SDL_SCANCODE_MENU` | |
1284
- | `sdl.keyboard.SCANCODE.SELECT` | `SDL_SCANCODE_SELECT` | |
1285
- | `sdl.keyboard.SCANCODE.STOP` | `SDL_SCANCODE_STOP` | |
1286
- | `sdl.keyboard.SCANCODE.AGAIN` | `SDL_SCANCODE_AGAIN` | redo |
1287
- | `sdl.keyboard.SCANCODE.UNDO` | `SDL_SCANCODE_UNDO` | |
1288
- | `sdl.keyboard.SCANCODE.CUT` | `SDL_SCANCODE_CUT` | |
1289
- | `sdl.keyboard.SCANCODE.COPY` | `SDL_SCANCODE_COPY` | |
1290
- | `sdl.keyboard.SCANCODE.PASTE` | `SDL_SCANCODE_PASTE` | |
1291
- | `sdl.keyboard.SCANCODE.FIND` | `SDL_SCANCODE_FIND` | |
1292
- | `sdl.keyboard.SCANCODE.MUTE` | `SDL_SCANCODE_MUTE` | |
1293
- | `sdl.keyboard.SCANCODE.VOLUMEUP` | `SDL_SCANCODE_VOLUMEUP` | |
1294
- | `sdl.keyboard.SCANCODE.VOLUMEDOWN` | `SDL_SCANCODE_VOLUMEDOWN` | |
1295
- | `sdl.keyboard.SCANCODE.KP_COMMA` | `SDL_SCANCODE_KP_COMMA` | |
1296
- | `sdl.keyboard.SCANCODE.KP_EQUALSAS400` | `SDL_SCANCODE_KP_EQUALSAS400` | |
1297
- | `sdl.keyboard.SCANCODE.INTERNATIONAL1` | `SDL_SCANCODE_INTERNATIONAL1` | used on Asian keyboards, see footnotes in USB doc |
1298
- | `sdl.keyboard.SCANCODE.INTERNATIONAL2` | `SDL_SCANCODE_INTERNATIONAL2` | |
1299
- | `sdl.keyboard.SCANCODE.INTERNATIONAL3` | `SDL_SCANCODE_INTERNATIONAL3` | Yen |
1300
- | `sdl.keyboard.SCANCODE.INTERNATIONAL4` | `SDL_SCANCODE_INTERNATIONAL4` | |
1301
- | `sdl.keyboard.SCANCODE.INTERNATIONAL5` | `SDL_SCANCODE_INTERNATIONAL5` | |
1302
- | `sdl.keyboard.SCANCODE.INTERNATIONAL6` | `SDL_SCANCODE_INTERNATIONAL6` | |
1303
- | `sdl.keyboard.SCANCODE.INTERNATIONAL7` | `SDL_SCANCODE_INTERNATIONAL7` | |
1304
- | `sdl.keyboard.SCANCODE.INTERNATIONAL8` | `SDL_SCANCODE_INTERNATIONAL8` | |
1305
- | `sdl.keyboard.SCANCODE.INTERNATIONAL9` | `SDL_SCANCODE_INTERNATIONAL9` | |
1306
- | `sdl.keyboard.SCANCODE.LANG1` | `SDL_SCANCODE_LANG1` | Hangul/English toggle |
1307
- | `sdl.keyboard.SCANCODE.LANG2` | `SDL_SCANCODE_LANG2` | Hanja conversion |
1308
- | `sdl.keyboard.SCANCODE.LANG3` | `SDL_SCANCODE_LANG3` | Katakana |
1309
- | `sdl.keyboard.SCANCODE.LANG4` | `SDL_SCANCODE_LANG4` | Hiragana |
1310
- | `sdl.keyboard.SCANCODE.LANG5` | `SDL_SCANCODE_LANG5` | Zenkaku/Hankaku |
1311
- | `sdl.keyboard.SCANCODE.LANG6` | `SDL_SCANCODE_LANG6` | |
1312
- | `sdl.keyboard.SCANCODE.LANG7` | `SDL_SCANCODE_LANG7` | |
1313
- | `sdl.keyboard.SCANCODE.LANG8` | `SDL_SCANCODE_LANG8` | |
1314
- | `sdl.keyboard.SCANCODE.LANG9` | `SDL_SCANCODE_LANG9` | |
1315
- | `sdl.keyboard.SCANCODE.ALTERASE` | `SDL_SCANCODE_ALTERASE` | Erase-Eaze |
1316
- | `sdl.keyboard.SCANCODE.SYSREQ` | `SDL_SCANCODE_SYSREQ` | |
1317
- | `sdl.keyboard.SCANCODE.CANCEL` | `SDL_SCANCODE_CANCEL` | |
1318
- | `sdl.keyboard.SCANCODE.CLEAR` | `SDL_SCANCODE_CLEAR` | |
1319
- | `sdl.keyboard.SCANCODE.PRIOR` | `SDL_SCANCODE_PRIOR` | |
1320
- | `sdl.keyboard.SCANCODE.RETURN2` | `SDL_SCANCODE_RETURN2` | |
1321
- | `sdl.keyboard.SCANCODE.SEPARATOR` | `SDL_SCANCODE_SEPARATOR` | |
1322
- | `sdl.keyboard.SCANCODE.OUT` | `SDL_SCANCODE_OUT` | |
1323
- | `sdl.keyboard.SCANCODE.OPER` | `SDL_SCANCODE_OPER` | |
1324
- | `sdl.keyboard.SCANCODE.CLEARAGAIN` | `SDL_SCANCODE_CLEARAGAIN` | |
1325
- | `sdl.keyboard.SCANCODE.CRSEL` | `SDL_SCANCODE_CRSEL` | |
1326
- | `sdl.keyboard.SCANCODE.EXSEL` | `SDL_SCANCODE_EXSEL` | |
1327
- | `sdl.keyboard.SCANCODE.KP_00` | `SDL_SCANCODE_KP_00` | |
1328
- | `sdl.keyboard.SCANCODE.KP_000` | `SDL_SCANCODE_KP_000` | |
1329
- | `sdl.keyboard.SCANCODE.THOUSANDSSEPARATOR` | `SDL_SCANCODE_THOUSANDSSEPARATOR` | |
1330
- | `sdl.keyboard.SCANCODE.DECIMALSEPARATOR` | `SDL_SCANCODE_DECIMALSEPARATOR` | |
1331
- | `sdl.keyboard.SCANCODE.CURRENCYUNIT` | `SDL_SCANCODE_CURRENCYUNIT` | |
1332
- | `sdl.keyboard.SCANCODE.CURRENCYSUBUNIT` | `SDL_SCANCODE_CURRENCYSUBUNIT` | |
1333
- | `sdl.keyboard.SCANCODE.KP_LEFTPAREN` | `SDL_SCANCODE_KP_LEFTPAREN` | |
1334
- | `sdl.keyboard.SCANCODE.KP_RIGHTPAREN` | `SDL_SCANCODE_KP_RIGHTPAREN` | |
1335
- | `sdl.keyboard.SCANCODE.KP_LEFTBRACE` | `SDL_SCANCODE_KP_LEFTBRACE` | |
1336
- | `sdl.keyboard.SCANCODE.KP_RIGHTBRACE` | `SDL_SCANCODE_KP_RIGHTBRACE` | |
1337
- | `sdl.keyboard.SCANCODE.KP_TAB` | `SDL_SCANCODE_KP_TAB` | |
1338
- | `sdl.keyboard.SCANCODE.KP_BACKSPACE` | `SDL_SCANCODE_KP_BACKSPACE` | |
1339
- | `sdl.keyboard.SCANCODE.KP_A` | `SDL_SCANCODE_KP_A` | |
1340
- | `sdl.keyboard.SCANCODE.KP_B` | `SDL_SCANCODE_KP_B` | |
1341
- | `sdl.keyboard.SCANCODE.KP_C` | `SDL_SCANCODE_KP_C` | |
1342
- | `sdl.keyboard.SCANCODE.KP_D` | `SDL_SCANCODE_KP_D` | |
1343
- | `sdl.keyboard.SCANCODE.KP_E` | `SDL_SCANCODE_KP_E` | |
1344
- | `sdl.keyboard.SCANCODE.KP_F` | `SDL_SCANCODE_KP_F` | |
1345
- | `sdl.keyboard.SCANCODE.KP_XOR` | `SDL_SCANCODE_KP_XOR` | |
1346
- | `sdl.keyboard.SCANCODE.KP_POWER` | `SDL_SCANCODE_KP_POWER` | |
1347
- | `sdl.keyboard.SCANCODE.KP_PERCENT` | `SDL_SCANCODE_KP_PERCENT` | |
1348
- | `sdl.keyboard.SCANCODE.KP_LESS` | `SDL_SCANCODE_KP_LESS` | |
1349
- | `sdl.keyboard.SCANCODE.KP_GREATER` | `SDL_SCANCODE_KP_GREATER` | |
1350
- | `sdl.keyboard.SCANCODE.KP_AMPERSAND` | `SDL_SCANCODE_KP_AMPERSAND` | |
1351
- | `sdl.keyboard.SCANCODE.KP_DBLAMPERSAND` | `SDL_SCANCODE_KP_DBLAMPERSAND` | |
1352
- | `sdl.keyboard.SCANCODE.KP_VERTICALBAR` | `SDL_SCANCODE_KP_VERTICALBAR` | |
1353
- | `sdl.keyboard.SCANCODE.KP_DBLVERTICALBAR` | `SDL_SCANCODE_KP_DBLVERTICALBAR` | |
1354
- | `sdl.keyboard.SCANCODE.KP_COLON` | `SDL_SCANCODE_KP_COLON` | |
1355
- | `sdl.keyboard.SCANCODE.KP_HASH` | `SDL_SCANCODE_KP_HASH` | |
1356
- | `sdl.keyboard.SCANCODE.KP_SPACE` | `SDL_SCANCODE_KP_SPACE` | |
1357
- | `sdl.keyboard.SCANCODE.KP_AT` | `SDL_SCANCODE_KP_AT` | |
1358
- | `sdl.keyboard.SCANCODE.KP_EXCLAM` | `SDL_SCANCODE_KP_EXCLAM` | |
1359
- | `sdl.keyboard.SCANCODE.KP_MEMSTORE` | `SDL_SCANCODE_KP_MEMSTORE` | |
1360
- | `sdl.keyboard.SCANCODE.KP_MEMRECALL` | `SDL_SCANCODE_KP_MEMRECALL` | |
1361
- | `sdl.keyboard.SCANCODE.KP_MEMCLEAR` | `SDL_SCANCODE_KP_MEMCLEAR` | |
1362
- | `sdl.keyboard.SCANCODE.KP_MEMADD` | `SDL_SCANCODE_KP_MEMADD` | |
1363
- | `sdl.keyboard.SCANCODE.KP_MEMSUBTRACT` | `SDL_SCANCODE_KP_MEMSUBTRACT` | |
1364
- | `sdl.keyboard.SCANCODE.KP_MEMMULTIPLY` | `SDL_SCANCODE_KP_MEMMULTIPLY` | |
1365
- | `sdl.keyboard.SCANCODE.KP_MEMDIVIDE` | `SDL_SCANCODE_KP_MEMDIVIDE` | |
1366
- | `sdl.keyboard.SCANCODE.KP_PLUSMINUS` | `SDL_SCANCODE_KP_PLUSMINUS` | |
1367
- | `sdl.keyboard.SCANCODE.KP_CLEAR` | `SDL_SCANCODE_KP_CLEAR` | |
1368
- | `sdl.keyboard.SCANCODE.KP_CLEARENTRY` | `SDL_SCANCODE_KP_CLEARENTRY` | |
1369
- | `sdl.keyboard.SCANCODE.KP_BINARY` | `SDL_SCANCODE_KP_BINARY` | |
1370
- | `sdl.keyboard.SCANCODE.KP_OCTAL` | `SDL_SCANCODE_KP_OCTAL` | |
1371
- | `sdl.keyboard.SCANCODE.KP_DECIMAL` | `SDL_SCANCODE_KP_DECIMAL` | |
1372
- | `sdl.keyboard.SCANCODE.KP_HEXADECIMAL` | `SDL_SCANCODE_KP_HEXADECIMAL` | |
1373
- | `sdl.keyboard.SCANCODE.LCTRL` | `SDL_SCANCODE_LCTRL` | |
1374
- | `sdl.keyboard.SCANCODE.LSHIFT` | `SDL_SCANCODE_LSHIFT` | |
1375
- | `sdl.keyboard.SCANCODE.LALT` | `SDL_SCANCODE_LALT` | alt, option |
1376
- | `sdl.keyboard.SCANCODE.LGUI` | `SDL_SCANCODE_LGUI` | windows, command (apple), meta |
1377
- | `sdl.keyboard.SCANCODE.RCTRL` | `SDL_SCANCODE_RCTRL` | |
1378
- | `sdl.keyboard.SCANCODE.RSHIFT` | `SDL_SCANCODE_RSHIFT` | |
1379
- | `sdl.keyboard.SCANCODE.RALT` | `SDL_SCANCODE_RALT` | alt gr, option |
1380
- | `sdl.keyboard.SCANCODE.RGUI` | `SDL_SCANCODE_RGUI` | windows, command (apple), meta |
1381
- | `sdl.keyboard.SCANCODE.MODE` | `SDL_SCANCODE_MODE` | |
1382
- | `sdl.keyboard.SCANCODE.AUDIONEXT` | `SDL_SCANCODE_AUDIONEXT` | |
1383
- | `sdl.keyboard.SCANCODE.AUDIOPREV` | `SDL_SCANCODE_AUDIOPREV` | |
1384
- | `sdl.keyboard.SCANCODE.AUDIOSTOP` | `SDL_SCANCODE_AUDIOSTOP` | |
1385
- | `sdl.keyboard.SCANCODE.AUDIOPLAY` | `SDL_SCANCODE_AUDIOPLAY` | |
1386
- | `sdl.keyboard.SCANCODE.AUDIOMUTE` | `SDL_SCANCODE_AUDIOMUTE` | |
1387
- | `sdl.keyboard.SCANCODE.MEDIASELECT` | `SDL_SCANCODE_MEDIASELECT` | |
1388
- | `sdl.keyboard.SCANCODE.WWW` | `SDL_SCANCODE_WWW` | |
1389
- | `sdl.keyboard.SCANCODE.MAIL` | `SDL_SCANCODE_MAIL` | |
1390
- | `sdl.keyboard.SCANCODE.CALCULATOR` | `SDL_SCANCODE_CALCULATOR` | |
1391
- | `sdl.keyboard.SCANCODE.COMPUTER` | `SDL_SCANCODE_COMPUTER` | |
1392
- | `sdl.keyboard.SCANCODE.AC_SEARCH` | `SDL_SCANCODE_AC_SEARCH` | |
1393
- | `sdl.keyboard.SCANCODE.AC_HOME` | `SDL_SCANCODE_AC_HOME` | |
1394
- | `sdl.keyboard.SCANCODE.AC_BACK` | `SDL_SCANCODE_AC_BACK` | |
1395
- | `sdl.keyboard.SCANCODE.AC_FORWARD` | `SDL_SCANCODE_AC_FORWARD` | |
1396
- | `sdl.keyboard.SCANCODE.AC_STOP` | `SDL_SCANCODE_AC_STOP` | |
1397
- | `sdl.keyboard.SCANCODE.AC_REFRESH` | `SDL_SCANCODE_AC_REFRESH` | |
1398
- | `sdl.keyboard.SCANCODE.AC_BOOKMARKS` | `SDL_SCANCODE_AC_BOOKMARKS` | |
1399
- | `sdl.keyboard.SCANCODE.BRIGHTNESSDOWN` | `SDL_SCANCODE_BRIGHTNESSDOWN` | |
1400
- | `sdl.keyboard.SCANCODE.BRIGHTNESSUP` | `SDL_SCANCODE_BRIGHTNESSUP` | |
1401
- | `sdl.keyboard.SCANCODE.DISPLAYSWITCH` | `SDL_SCANCODE_DISPLAYSWITCH` | display mirroring/dual display switch, video mode switch |
1402
- | `sdl.keyboard.SCANCODE.KBDILLUMTOGGLE` | `SDL_SCANCODE_KBDILLUMTOGGLE` | |
1403
- | `sdl.keyboard.SCANCODE.KBDILLUMDOWN` | `SDL_SCANCODE_KBDILLUMDOWN` | |
1404
- | `sdl.keyboard.SCANCODE.KBDILLUMUP` | `SDL_SCANCODE_KBDILLUMUP` | |
1405
- | `sdl.keyboard.SCANCODE.EJECT` | `SDL_SCANCODE_EJECT` | |
1406
- | `sdl.keyboard.SCANCODE.SLEEP` | `SDL_SCANCODE_SLEEP` | |
1407
- | `sdl.keyboard.SCANCODE.APP1` | `SDL_SCANCODE_APP1` | |
1408
- | `sdl.keyboard.SCANCODE.APP2` | `SDL_SCANCODE_APP2` | |
1409
- | `sdl.keyboard.SCANCODE.AUDIOREWIND` | `SDL_SCANCODE_AUDIOREWIND` | |
1410
- | `sdl.keyboard.SCANCODE.AUDIOFASTFORWARD` | `SDL_SCANCODE_AUDIOFASTFORWARD` | |
1411
-
1412
- ### Virtual keys
1413
-
1414
- String values used to represent virtual keys in the context of the current keyboard mapping.
1415
- Note that some keys do not correspond to any virtual key.
1416
- A Key can be either one of the values below __or__ any unicode character.
1417
- Keys that produce characters are represented by that character.
1418
- All others are represented by one of these values:
1419
-
1420
- `'&&'`, `'+/-'`, `'||'`, `'00'`, `'000'`, `'again'`, `'alt'`, `'altErase'`, `'app1'`, `'app2'`, `'application'`, `'audioFastForward'`, `'audioMute'`, `'audioNext'`, `'audioPlay'`, `'audioPrev'`, `'audioRewind'`, `'audioStop'`, `'back'`, `'backspace'`, `'binary'`, `'bookmarks'`, `'brightnessDown'`, `'brightnessUp'`, `'calculator'`, `'cancel'`, `'capsLock'`, `'clear'`, `'clearEntry'`, `'computer'`, `'copy'`, `'crSel'`, `'ctrl'`, `'currencySubUnit'`, `'currencyUnit'`, `'cut'`, `'decimal'`, `'decimalSeparator'`, `'delete'`, `'displaySwitch'`, `'down'`, `'eject'`, `'end'`, `'enter'`, `'escape'`, `'execute'`, `'exSel'`, `'f1'`, `'f2'`, `'f3'`, `'f4'`, `'f5'`, `'f6'`, `'f7'`, `'f8'`, `'f9'`, `'f10'`, `'f11'`, `'f12'`, `'f13'`, `'f14'`, `'f15'`, `'f16'`, `'f17'`, `'f18'`, `'f19'`, `'f20'`, `'f21'`, `'f22'`, `'f23'`, `'f24'`, `'find'`, `'forward'`, `'gui'`, `'help'`, `'hexadecimal'`, `'home'`, `'illumDown'`, `'illumToggle'`, `'illumUp'`, `'insert'`, `'left'`, `'mail'`, `'mediaSelect'`, `'memAdd'`, `'memClear'`, `'memDivide'`, `'memMultiply'`, `'memRecall'`, `'memStore'`, `'memSubtract'`, `'menu'`, `'modeSwitch'`, `'mute'`, `'numlock'`, `'octal'`, `'oper'`, `'out'`, `'pageDown'`, `'pageUp'`, `'paste'`, `'pause'`, `'power'`, `'printScreen'`, `'prior'`, `'refresh'`, `'return'`, `'right'`, `'scrollLock'`, `'search'`, `'select'`, `'separator'`, `'shift'`, `'sleep'`, `'space'`, `'stop'`, `'sysReq'`, `'tab'`, `'thousandsSeparator'`, `'undo'`, `'up'`, `'volumeDown'`, `'volumeUp'`, `'www'`, `'xor'`.
1421
-
1422
- ### sdl.keyboard.getKey(scancode)
1423
-
1424
- * `scancode: `[`<Scancode>`](#enum-scancode)
1425
- * Returns: [`<Key>`](#virtual-keys)`|<null>`
1426
-
1427
- Maps a scancode to the corresponding key based on the current keyboard mapping.
1428
-
1429
- ### sdl.keyboard.getScancode(key)
1430
-
1431
- * `key: `[`<Key>`](#virtual-keys)
1432
- * Returns: [`<Scancode>`](#enum-scancode)
1433
-
1434
- Maps a key to the corresponding scancode based on the current keyboard mapping.
1435
- If multiple physical keys produce the same virtual key, then only the first one will be returned.
1436
-
1437
- ### sdl.keyboard.getState()
1438
-
1439
- * Returns: `<boolean[]>` an object representing the state of each key.
1440
-
1441
- The returned array can be indexed with [`Scancode`](#enum-scancode) values.
1442
- Pressed keys will correspond to `true` values.
1443
-
1444
-
1445
- ## sdl.mouse
1446
-
1447
- ### Mouse cursors
1448
-
1449
- String values used to represent the types of cursors available on most systems.
1450
-
1451
- | Value | Corresponding `SDL_SystemCursor` | Description |
1452
- | --- | --- | --- |
1453
- | `'arrow'` | `SDL_SYSTEM_CURSOR_ARROW` | arrow |
1454
- | `'ibeam'` | `SDL_SYSTEM_CURSOR_IBEAM` | i-beam |
1455
- | `'wait'` | `SDL_SYSTEM_CURSOR_WAIT` | wait |
1456
- | `'crosshair'` | `SDL_SYSTEM_CURSOR_CROSSHAIR` | crosshair |
1457
- | `'waitarrow'` | `SDL_SYSTEM_CURSOR_WAITARROW` | small wait cursor (or wait if not available) |
1458
- | `'sizenwse'` | `SDL_SYSTEM_CURSOR_SIZENWSE` | double arrow pointing northwest and southeast |
1459
- | `'sizenesw'` | `SDL_SYSTEM_CURSOR_SIZENESW` | double arrow pointing northeast and southwest |
1460
- | `'sizewe'` | `SDL_SYSTEM_CURSOR_SIZEWE` | double arrow pointing west and east |
1461
- | `'sizens'` | `SDL_SYSTEM_CURSOR_SIZENS` | double arrow pointing north and south |
1462
- | `'sizeall'` | `SDL_SYSTEM_CURSOR_SIZEALL` | four pointed arrow pointing north, south, east, and west |
1463
- | `'no'` | `SDL_SYSTEM_CURSOR_NO` | slashed circle or crossbones |
1464
- | `'hand'` | `SDL_SYSTEM_CURSOR_HAND` | hand |
1465
-
1466
- ### Enum: BUTTON
1467
-
1468
- Used to represent the buttons on a mouse.
1469
- A mouse can have many buttons, but the values for the three most common ones are represented in this enum.
1470
-
1471
- | Value | Corresponding `SDL_BUTTON_*` |
1472
- | --- | --- |
1473
- | `sdl.mouse.BUTTON.LEFT` | `SDL_BUTTON_LEFT` |
1474
- | `sdl.mouse.BUTTON.MIDDLE` | `SDL_BUTTON_MIDDLE` |
1475
- | `sdl.mouse.BUTTON.RIGHT` | `SDL_BUTTON_RIGHT` |
1476
-
1477
- ### sdl.mouse.getButton(button)
1478
-
1479
- * `button: <number>` The index of the button.
1480
- * Returns: `<boolean>` Will be `true` if the button is pressed.
1481
-
1482
- Queries the state of a single mouse button.
1483
-
1484
- ### sdl.mouse.position
1485
-
1486
- * `<object>`
1487
- * `x: <number>` The x position of the mouse, relative to the screen.
1488
- * `y: <number>` The y position of the mouse, relative to the screen.
1489
-
1490
- The position of the mouse on the screen.
1491
-
1492
- ### sdl.mouse.setPosition(x, y)
1493
-
1494
- * `x: <number>` The new x position of the mouse, relative to the screen.
1495
- * `y: <number>` The new y position of the mouse, relative to the screen.
1496
-
1497
- Moves the mouse to the specified position.
1498
-
1499
- ### sdl.mouse.setCursor(cursor)
1500
-
1501
- * `cursor: `[`<MouseCursor>`](#mouse-cursors) The icon to use for the cursor.
1502
-
1503
- Changes the icon that is displayed for the mouse cursor.
1504
-
1505
- ### sdl.mouse.setCursorImage(width, height, stride, format, buffer, x, y)
1506
-
1507
- * `width, height, stride, format, buffer: `[`<Image>`](#image-data) The image to use as a cursor.
1508
- * `x: <number>` The x position of the cursor image's hotspot.
1509
- * `y: <number>` The y position of the cursor image's hotspot.
1510
-
1511
- Sets a image to be the mouse cursor.
1512
- The hotspot represents the pixel that is considered to be under the mouse.
1513
-
1514
- ### sdl.mouse.showCursor([show])
1515
-
1516
- * `show: <boolean>` If `true` then the mouse cursor will be visible.
1517
- Default `true`.
1518
-
1519
- Changes the visibility of the mouse cursor.
1520
-
1521
- ### sdl.mouse.hideCursor()
1522
-
1523
- Equivalent to [`sdl.mouse.showCursor(false)`](#sdlmouseshowcursorshow).
1524
-
1525
- ### sdl.mouse.capture([capture])
1526
-
1527
- * `capture: <boolean>` If `true` the mouse will be captured by the current window.
1528
- Default `true`.
1529
-
1530
- When the mouse has been captured you will continue receiving mouse events even if the mouse is not over a window.
1531
-
1532
- ### sdl.mouse.uncapture()
1533
-
1534
- Equivalent to [`sdl.mouse.capture(false)`](#sdlmousecapturecapture).
1535
-
1536
-
1537
2178
  ## sdl.clipboard
1538
2179
 
1539
2180
  ### Event: 'update'
@@ -1554,21 +2195,32 @@ The current text value on the clipboard.
1554
2195
  Changes the text contents of the clipboard.
1555
2196
 
1556
2197
 
2198
+ ## Building from source
2199
+
2200
+ If there are no prebuilt binaries available for your platform, `@kmamal/sdl` will try to compile itself during installation.
2201
+ A few prerequisites are necessary for that to work:
1557
2202
 
1558
- ## Miscellanea
2203
+ First, make sure you have installed [node-gyp](https://github.com/nodejs/node-gyp#installation) as well as its dependencies.
1559
2204
 
2205
+ On Mac, you will also need to install `xquartz` so that SDL can find the X11 headers it needs.
2206
+ You can do that via `brew install xquartz`.
1560
2207
 
1561
- ### Installing SDL2
2208
+ You don't need to install any SDL libraries or headers.
2209
+ These will be downloaded automatically through the [@kmamal/build-sdl](https://github.com/kmamal/build-sdl) package.
2210
+ If `@kmamal/build-sdl` has no prebuilt library for your platform, it will try to compile one on the spot.
2211
+ You will need to have `cmake` installed for that to work.
1562
2212
 
1563
- This should not be necessary, since this package bundles the SDL2 runtime library along with its binaries, but you never know...
2213
+ ---
1564
2214
 
1565
- This package depends on SDL2 `>=2.0.5`.
1566
- To install it on your system you might have to download one of the [SDL2 Runtime Binaries](https://www.libsdl.org/download-2.0.php).
1567
- * __Linux:__ Run `sudo apt install libsdl2-2.0-0` or whatever the equivalent command is for your package manager.
1568
- * __Mac:__ Download the `.dmg` file, open it, and copy the `SDL2.framework` to `/Library/Frameworks`.
1569
- * __Windows:__ Download the `.zip` file, extract it, and copy the `.dll` files to a path Node.js can link them from. This will usually be your system directory (`C:\Windows`) but see [here](https://docs.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-search-order) for other paths where Windows will look for `.dll` files to link.
2215
+ You could also have found your way to the "Building from source" section because you are trying to contribute to this package. There are some npm scripts in `package.json` that could be of use to you:
2216
+ * `npm run clean` deletes all folders that are created during the build, as well as `node_modules`.
2217
+ * `npm run download-release` downloads the prebuilt binaries. This is the first thing the install script tries to do.
2218
+ * `npm run download-sdl` downloads the SDL headers and libraries from `@kmamal/build-sdl` so you can compile against them in later steps. This is the second step in the install script, after `download-release` has failed.
2219
+ * `npm run build` prepares the environment variables and calls `node-gyp` to build the package.
2220
+ * `NODE_SDL_FROM_SOURCE=1 npm install` runs the install script normally, but skips the inital attempt to download the binaries, and goes straight to building from source.
1570
2221
 
2222
+ The SDL headers and libs get downloaded to `sdl/`, the build happens in `build/`, and the final binaries get collected into `dist/`.
1571
2223
 
1572
- ### Building from source
2224
+ The way I normally work is I run `npm run clean` to start fresh, then run `NODE_SDL_FROM_SOURCE=1 npm i` once to prepare everything, then as I make changes I run `npm run build` ro re-build the package.
1573
2225
 
1574
- // TODO
2226
+ Have fun!