@kmamal/sdl 0.11.13 → 1.0.0-2

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.
Files changed (86) hide show
  1. package/CHANGELOG.md +249 -0
  2. package/README.md +26 -2685
  3. package/binding.gyp +82 -65
  4. package/package.json +17 -11
  5. package/scripts/build-sdl.mjs +15 -7
  6. package/scripts/build.mjs +30 -15
  7. package/scripts/download-release.mjs +9 -6
  8. package/scripts/download-sdl.mjs +9 -6
  9. package/scripts/install.mjs +13 -5
  10. package/scripts/util/common.js +9 -1
  11. package/src/javascript/audio/audio-playback-stream.js +50 -0
  12. package/src/javascript/audio/audio-recording-stream.js +32 -0
  13. package/src/javascript/audio/{audio-instance.js → audio-stream.js} +35 -32
  14. package/src/javascript/audio/device.js +34 -6
  15. package/src/javascript/audio/format-helpers.js +26 -35
  16. package/src/javascript/audio/index.js +37 -26
  17. package/src/javascript/audio/prevent-exit.js +19 -9
  18. package/src/javascript/cleanup.js +19 -10
  19. package/src/javascript/enums.js +5 -0
  20. package/src/javascript/events/events-via-poll.js +25 -7
  21. package/src/javascript/events/index.js +274 -175
  22. package/src/javascript/gamepad/device.js +23 -0
  23. package/src/javascript/gamepad/gamepad-instance.js +209 -0
  24. package/src/javascript/gamepad/index.js +51 -0
  25. package/src/javascript/globals.js +8 -5
  26. package/src/javascript/helpers.js +34 -7
  27. package/src/javascript/index.js +5 -3
  28. package/src/javascript/joystick/device.js +5 -10
  29. package/src/javascript/joystick/index.js +7 -7
  30. package/src/javascript/joystick/joystick-instance.js +79 -42
  31. package/src/javascript/joystick/shared.js +88 -0
  32. package/src/javascript/keyboard/index.js +6 -4
  33. package/src/javascript/keyboard/key-mapping.js +70 -28
  34. package/src/javascript/mouse/index.js +21 -10
  35. package/src/javascript/sensor/devices.js +17 -0
  36. package/src/javascript/sensor/index.js +2 -16
  37. package/src/javascript/sensor/sensor-instance.js +20 -6
  38. package/src/javascript/touch/devices.js +17 -0
  39. package/src/javascript/touch/index.js +3 -7
  40. package/src/javascript/video/format-helpers.js +99 -0
  41. package/src/javascript/video/index.js +37 -5
  42. package/src/javascript/video/window.js +280 -134
  43. package/src/native/audio.cpp +182 -58
  44. package/src/native/audio.h +10 -5
  45. package/src/native/clipboard.cpp +22 -5
  46. package/src/native/cocoa-window.h +1 -0
  47. package/src/native/cocoa-window.mm +1 -1
  48. package/src/native/enums.cpp +91 -58
  49. package/src/native/events.cpp +437 -284
  50. package/src/native/events.h +18 -12
  51. package/src/native/gamepad.cpp +185 -0
  52. package/src/native/gamepad.h +27 -0
  53. package/src/native/global.cpp +173 -167
  54. package/src/native/global.h +0 -2
  55. package/src/native/joystick.cpp +287 -225
  56. package/src/native/joystick.h +7 -6
  57. package/src/native/keyboard.cpp +28 -8
  58. package/src/native/keyboard.h +4 -2
  59. package/src/native/module.cpp +14 -8
  60. package/src/native/mouse.cpp +54 -34
  61. package/src/native/mouse.h +0 -1
  62. package/src/native/power.cpp +10 -4
  63. package/src/native/power.h +1 -1
  64. package/src/native/sensor.cpp +52 -52
  65. package/src/native/sensor.h +1 -1
  66. package/src/native/touch.cpp +45 -24
  67. package/src/native/touch.h +1 -1
  68. package/src/native/video.cpp +115 -75
  69. package/src/native/video.h +5 -2
  70. package/src/native/window.cpp +406 -318
  71. package/src/native/window.h +3 -1
  72. package/src/types/helpers.d.ts +44 -19
  73. package/src/types/index.d.ts +343 -255
  74. package/scripts/util/fetch.js +0 -85
  75. package/src/javascript/audio/audio-playback-instance.js +0 -23
  76. package/src/javascript/audio/audio-recording-instance.js +0 -17
  77. package/src/javascript/controller/controller-instance.js +0 -160
  78. package/src/javascript/controller/device.js +0 -26
  79. package/src/javascript/controller/index.js +0 -33
  80. package/src/javascript/events/reconcile-audio-devices.js +0 -16
  81. package/src/javascript/events/reconcile-displays.js +0 -17
  82. package/src/javascript/events/reconcile-joystick-and-controller-devices.js +0 -40
  83. package/src/javascript/events/reconcile.js +0 -61
  84. package/src/javascript/video/display.js +0 -4
  85. package/src/native/controller.cpp +0 -192
  86. package/src/native/controller.h +0 -26
package/README.md CHANGED
@@ -4,40 +4,51 @@
4
4
  [![Dependencies](https://img.shields.io/librariesio/release/npm/@kmamal/sdl)](https://libraries.io/npm/@kmamal%2Fsdl)
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
6
 
7
- SDL bindings for Node.js. Provides access to systems that are not normally available to Node.js applications:
7
+ > [!NOTE]
8
+ > This version migrated from SDL2 to SDL3.
9
+ > Most of the API is unchanged, but several changes break compatibility.
10
+ > The [migration guide](https://github.com/kmamal/node-sdl/tree/master/docs/migrating-to-sdl3.md) lists them all.
11
+
12
+ SDL bindings for Node.js. Gives applications access to systems that Node.js does not normally provide:
8
13
 
9
14
  - 💻 Window management
10
15
  - ⌨ Keyboard
11
16
  - 🖱 Mouse
12
17
  - 🕹 Joysticks
13
- - 🎮 Controllers
18
+ - 🎮 Gamepads
14
19
  - 🔈 Audio playback
15
20
  - 🎤 Audio recording
16
21
  - 📋 Clipboard manipulation
17
22
  - 🔋 Battery status
18
23
  - 🧭 Sensors
19
24
 
20
- Also allows using Canvas2D, WebGL, and WebGPU without a browser, through these libraries:
25
+ The bindings also let you use Canvas2D, WebGL, and WebGPU without a browser, through these libraries:
21
26
 
22
- - __Canvas2D:__ [@napi-rs/canvas](https://www.npmjs.com/package/@napi-rs/canvas). In my experience, this is the fastest library out of the many available on npm.
23
- - __WebGL:__ [@kmamal/gl](https://github.com/kmamal/headless-gl#readme). This is a fork of [headless-gl](https://github.com/stackgl/headless-gl#readme) that I've modified to render directly to SDL windows.
24
- - __WebGPU:__ [@kmamal/gpu](https://github.com/kmamal/gpu#readme). This is a fork of [Google Dawn](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/dawn/node/) that I've modified to render directly to SDL windows.
27
+ - __Canvas2D:__ [@napi-rs/canvas](https://www.npmjs.com/package/@napi-rs/canvas). In my experience, it is the fastest of the many canvas libraries on npm.
28
+ - __WebGL:__ [@kmamal/gl](https://github.com/kmamal/headless-gl#readme). I forked [headless-gl](https://github.com/stackgl/headless-gl#readme) and modified it to render directly to SDL windows.
29
+ - __WebGPU:__ [@kmamal/gpu](https://github.com/kmamal/gpu#readme). I forked [Google Dawn](https://dawn.googlesource.com/dawn/+/refs/heads/main/src/dawn/node/) and modified it to render directly to SDL windows.
25
30
 
26
- Officially supports Linux (x64, arm64), Mac (x64, arm64), and Windows (x64).
27
- Should theoretically work on any system supported by both SDL and Node.js, but I haven't tried any others.
28
- Prebuilt binaries are available for the supported architectures.
31
+ The package officially supports Linux (X11 and Wayland), Mac, and Windows.
32
+ It should work on any system that both SDL and Node.js support, but I haven't tried others.
33
+ Prebuilt binaries exist for x64 and arm architectures on all supported platforms.
29
34
 
30
35
  ## Installation
31
36
 
32
- This package is self-contained. Just run:
37
+ The package is self-contained. Just run:
33
38
 
34
39
  ```bash
35
40
  npm install @kmamal/sdl
36
41
  ```
37
42
 
38
- You do __not__ have to manually install any other libs or DLLs to your system. A compatible version of SDL will be automatically downloaded by the install script and placed inside `node_modules` along with this lib's prebuilt binding binaries.
43
+ You do __not__ need to install any other libraries or DLLs yourself. The install script downloads a compatible version of SDL and places it inside `node_modules`, next to the package's prebuilt binding binaries.
44
+
45
+ Future versions of npm will require you to approve scripts before they run. Approve this package's script with:
46
+
47
+ ```bash
48
+ npm install-scripts approve @kmamal/sdl
49
+ ```
39
50
 
40
- (But if the install script fails, have a look at the instructions for [building the package manually](#building-from-source))
51
+ If the install script fails, follow the instructions for [building the package manually](https://github.com/kmamal/node-sdl/tree/master/docs/building-from-source.md).
41
52
 
42
53
  ## Examples
43
54
 
@@ -123,2679 +134,9 @@ renderer.swap()
123
134
 
124
135
  ```
125
136
 
126
- ### More examples
127
-
128
- Check the [`examples/`](https://github.com/kmamal/node-sdl/tree/master/examples#readme) folder.
129
-
130
- # API Reference
131
-
132
- ## Contents
133
-
134
- - [sdl](#sdl)
135
- - [sdl.info](#sdlinfo)
136
- - [sdl.video](#sdlvideo)
137
- - [Image data](#image-data)
138
- - [High-DPI](#high-dpi)
139
- - [Pixel formats](#pixel-formats)
140
- - [Event: 'displayAdd'](#event-displayadd)
141
- - [Event: 'displayRemove'](#event-displayremove)
142
- - [Event: 'displayOrient'](#event-displayorient)
143
- - [Event: 'displayMove'](#event-displaymove)
144
- - [sdl.video.displays](#sdlvideodisplays)
145
- - [sdl.video.windows](#sdlvideowindows)
146
- - [sdl.video.focused](#sdlvideofocused)
147
- - [sdl.video.hovered](#sdlvideohovered)
148
- - [sdl.video.createWindow([options])](#sdlvideocreatewindowoptions)
149
- - [class Window](#class-window)
150
- - [Event: 'show'](#event-show)
151
- - [Event: 'hide'](#event-hide)
152
- - [Event: 'expose'](#event-expose)
153
- - [Event: 'minimize'](#event-minimize)
154
- - [Event: 'maximize'](#event-maximize)
155
- - [Event: 'restore'](#event-restore)
156
- - [Event: 'move'](#event-move)
157
- - [Event: 'resize'](#event-resize)
158
- - [Event: 'displayChange'](#event-displaychange)
159
- - [Event: 'focus'](#event-focus)
160
- - [Event: 'blur'](#event-blur)
161
- - [Event: 'hover'](#event-hover)
162
- - [Event: 'leave'](#event-leave)
163
- - [Event: 'beforeClose'](#event-beforeclose)
164
- - [Event: 'close'](#event-close)
165
- - [Event: 'keyDown'](#event-keydown)
166
- - [Event: 'keyUp'](#event-keyup)
167
- - [Event: 'textInput'](#event-textinput)
168
- - [Event: 'mouseButtonDown'](#event-mousebuttondown)
169
- - [Event: 'mouseButtonUp'](#event-mousebuttonup)
170
- - [Event: 'mouseMove'](#event-mousemove)
171
- - [Event: 'mouseWheel'](#event-mousewheel)
172
- - [Event: 'fingerDown'](#event-fingerdown)
173
- - [Event: 'fingerUp'](#event-fingerup)
174
- - [Event: 'fingerMove'](#event-fingermove)
175
- - [Event: 'dropBegin'](#event-dropbegin)
176
- - [Event: 'dropText'](#event-droptext)
177
- - [Event: 'dropFile'](#event-dropfile)
178
- - [Event: 'dropComplete'](#event-dropcomplete)
179
- - [window.id](#windowid)
180
- - [window.title](#windowtitle)
181
- - [window.setTitle(title)](#windowsettitletitle)
182
- - [window.x](#windowx)
183
- - [window.y](#windowy)
184
- - [window.setPosition(x, y)](#windowsetpositionx-y)
185
- - [window.width](#windowwidth)
186
- - [window.height](#windowheight)
187
- - [window.pixelWidth](#windowpixelwidth)
188
- - [window.pixelHeight](#windowpixelheight)
189
- - [window.setSize(width, height)](#windowsetsizewidth-height)
190
- - [window.setSizeInPixels(pixelWidth, pixelHeight)](#windowsetsizeinpixelspixelwidth-pixelheight)
191
- - [window.display](#windowdisplay)
192
- - [window.visible](#windowvisible)
193
- - [window.show([show])](#windowshowshow)
194
- - [window.hide()](#windowhide)
195
- - [window.fullscreen](#windowfullscreen)
196
- - [window.setFullscreen(fullscreen)](#windowsetfullscreenfullscreen)
197
- - [window.resizable](#windowresizable)
198
- - [window.setResizable(resizable)](#windowsetresizableresizable)
199
- - [window.borderless](#windowborderless)
200
- - [window.setBorderless(borderless)](#windowsetborderlessborderless)
201
- - [window.alwaysOnTop](#windowalwaysontop)
202
- - [window.accelerated](#windowaccelerated)
203
- - [window.setAccelerated(accelerated)](#windowsetacceleratedaccelerated)
204
- - [window.vsync](#windowvsync)
205
- - [window.setVsync(vsync)](#windowsetvsyncvsync)
206
- - [window.opengl](#windowopengl)
207
- - [window.webgpu](#windowwebgpu)
208
- - [window.native](#windownative)
209
- - [window.maximized](#windowmaximized)
210
- - [window.maximize()](#windowmaximize)
211
- - [window.minimized](#windowminimized)
212
- - [window.minimize()](#windowminimize)
213
- - [window.restore()](#windowrestore)
214
- - [window.focused](#windowfocused)
215
- - [window.focus()](#windowfocus)
216
- - [window.hovered](#windowhovered)
217
- - [window.skipTaskbar](#windowskiptaskbar)
218
- - [window.popupMenu](#windowpopupmenu)
219
- - [window.tooltip](#windowtooltip)
220
- - [window.utility](#windowutility)
221
- - [window.render(width, height, stride, format, buffer[, options])](#windowrenderwidth-height-stride-format-buffer-options)
222
- - [window.setIcon(width, height, stride, format, buffer)](#windowseticonwidth-height-stride-format-buffer)
223
- - [window.flash([untilFocused])](#windowflashuntilfocused)
224
- - [window.stopFlashing()](#windowstopflashing)
225
- - [window.destroyed](#windowdestroyed)
226
- - [window.destroy()](#windowdestroy)
227
- - [window.destroyGently()](#windowdestroygently)
228
- - [sdl.keyboard](#sdlkeyboard)
229
- - [Virtual keys](#virtual-keys)
230
- - [Enum: SCANCODE](#enum-scancode)
231
- - [Event: 'keymapChange'](#event-keymapchange)
232
- - [sdl.keyboard.getKey(scancode)](#sdlkeyboardgetkeyscancode)
233
- - [sdl.keyboard.getScancode(key)](#sdlkeyboardgetscancodekey)
234
- - [sdl.keyboard.getState()](#sdlkeyboardgetstate)
235
- - [sdl.mouse](#sdlmouse)
236
- - [Enum: BUTTON](#enum-button)
237
- - [sdl.mouse.getButton(button)](#sdlmousegetbuttonbutton)
238
- - [sdl.mouse.position](#sdlmouseposition)
239
- - [sdl.mouse.setPosition(x, y)](#sdlmousesetpositionx-y)
240
- - [sdl.mouse.setCursor(cursor)](#sdlmousesetcursorcursor)
241
- - [sdl.mouse.resetCursor()](#sdlmouseresetcursor)
242
- - [sdl.mouse.setCursorImage(width, height, stride, format, buffer, x, y)](#sdlmousesetcursorimagewidth-height-stride-format-buffer-x-y)
243
- - [sdl.mouse.showCursor([show])](#sdlmouseshowcursorshow)
244
- - [sdl.mouse.hideCursor()](#sdlmousehidecursor)
245
- - [sdl.mouse.redrawCursor()](#sdlmouseredrawcursor)
246
- - [sdl.mouse.capture([capture])](#sdlmousecapturecapture)
247
- - [sdl.mouse.uncapture()](#sdlmouseuncapture)
248
- - [sdl.joystick](#sdljoystick)
249
- - [Hat positions](#hat-positions)
250
- - [Power levels](#power-levels)
251
- - [Event: 'deviceAdd'](#joystick-event-deviceadd)
252
- - [Event: 'deviceRemove'](#joystick-event-deviceremove)
253
- - [sdl.joystick.devices](#sdljoystickdevices)
254
- - [sdl.joystick.openDevice(device)](#sdljoystickopendevicedevice)
255
- - [class JoystickInstance](#class-joystickinstance)
256
- - [Event: 'axisMotion'](#joystick-instance-event-axismotion)
257
- - [Event: 'ballMotion'](#event-ballmotion)
258
- - [Event: 'buttonDown'](#joystick-instance-event-buttondown)
259
- - [Event: 'buttonUp'](#joystick-instance-event-buttonup)
260
- - [Event: 'hatMotion'](#event-hatmotion)
261
- - [Event: 'powerUpdate'](#joystick-instance-event-power-update)
262
- - [Event: 'close'](#joystick-instance-event-close)
263
- - [joystickInstance.device](#joystickinstancedevice)
264
- - [joystickInstance.firmwareVersion](#joystickinstancefirmwareversion)
265
- - [joystickInstance.serialNumber](#joystickinstanceserialnumber)
266
- - [joystickInstance.axes](#joystickinstanceaxes)
267
- - [joystickInstance.balls](#joystickinstanceballs)
268
- - [joystickInstance.buttons](#joystickinstancebuttons)
269
- - [joystickInstance.hats](#joystickinstancehats)
270
- - [joystickInstance.power](#joystickinstancepower)
271
- - [joystickInstance.setPlayer(index)](#joystickinstancesetplayerindex)
272
- - [joystickInstance.resetPlayer()](#joystickinstanceresetplayer)
273
- - [joystickInstance.hasLed](#joystickinstancehasled)
274
- - [joystickInstance.setLed(red, green, blue)](#joystickinstancesetledred-green-blue)
275
- - [joystickInstance.hasRumble](#joystickinstancehasrumble)
276
- - [joystickInstance.rumble([low[, high[, duration]]])](#joystickinstancerumblelow-high-duration)
277
- - [joystickInstance.stopRumble()](#joystickinstancestoprumble)
278
- - [joystickInstance.hasRumbleTriggers](#joystickinstancehasrumbletriggers)
279
- - [joystickInstance.rumbleTriggers([left[, right[, duration]]])](#joystickinstancerumbletriggersleft-right-duration)
280
- - [joystickInstance.stopRumbleTriggers()](#joystickinstancestoprumbletriggers)
281
- - [joystickInstance.closed](#joystickinstanceclosed)
282
- - [joystickInstance.close()](#joystickinstanceclose)
283
- - [sdl.controller](#sdlcontroller)
284
- - [Event: 'deviceAdd'](#controller-event-deviceadd)
285
- - [Event: 'deviceRemove'](#controller-event-deviceremove)
286
- - [sdl.controller.addMappings(mappings)](#sdlcontrolleraddmappingsmappings)
287
- - [sdl.controller.devices](#sdlcontrollerdevices)
288
- - [sdl.controller.openDevice(device)](#sdlcontrolleropendevicedevice)
289
- - [class ControllerInstance](#class-controllerinstance)
290
- - [Event: 'axisMotion'](#controller-instance-event-axismotion)
291
- - [Event: 'buttonDown'](#controller-instance-event-buttondown)
292
- - [Event: 'buttonUp'](#controller-instance-event-buttonup)
293
- - [Event: 'powerUpdate'](#controller-instance-event-power-update)
294
- - [Event: 'steamHandleUpdate'](#event-steamhandleupdate)
295
- - [Event: 'remap'](#event-remap)
296
- - [Event: 'close'](#controller-instance-event-close)
297
- - [controllerInstance.device](#controllerinstancedevice)
298
- - [controllerInstance.firmwareVersion](#controllerinstancefirmwareversion)
299
- - [controllerInstance.serialNumber](#controllerinstanceserialnumber)
300
- - [controllerInstance.steamHandle](#controllerinstancesteamhandle)
301
- - [controllerInstance.axes](#controllerinstanceaxes)
302
- - [controllerInstance.buttons](#controllerinstancebuttons)
303
- - [controllerInstance.power](#controllerinstancepower)
304
- - [controllerInstance.setPlayer(index)](#controllerinstancesetplayerindex)
305
- - [controllerInstance.resetPlayer()](#controllerinstanceresetplayer)
306
- - [controllerInstance.hasLed](#controllerinstancehasled)
307
- - [controllerInstance.setLed(red, green, blue)](#controllerinstancesetledred-green-blue)
308
- - [controllerInstance.hasRumble](#controllerinstancehasrumble)
309
- - [controllerInstance.rumble([low[, high[, duration]]])](#controllerinstancerumblelow-high-duration)
310
- - [controllerInstance.stopRumble()](#controllerinstancestoprumble)
311
- - [controllerInstance.hasRumbleTriggers](#controllerinstancehasrumbletriggers)
312
- - [controllerInstance.rumbleTriggers([left[, right[, duration]]])](#controllerinstancerumbletriggersleft-right-duration)
313
- - [controllerInstance.stopRumbleTriggers()](#controllerinstancestoprumbletriggers)
314
- - [controllerInstance.closed](#controllerinstanceclosed)
315
- - [controllerInstance.close()](#controllerinstanceclose)
316
- - [sdl.sensor](#sdlsensor)
317
- - [sdl.sensor.STANDARD_GRAVITY](#sdlsensorstandard_gravity)
318
- - [sdl.sensor.devices](#sdlsensordevices)
319
- - [sdl.sensor.openDevice(device)](#sdlsensoropendevicedevice)
320
- - [class SensorInstance](#class-sensorinstance)
321
- - [Event: 'update'](#sensor-instance-event-update)
322
- - [sensorInstance.device](#sensorinstancedevice)
323
- - [sensorInstance.data](#sensorinstancedata)
324
- - [sensorInstance.closed](#sensorinstanceclosed)
325
- - [sensorInstance.close()](#sensorinstanceclose)
326
- - [sdl.audio](#sdlaudio)
327
- - [Audio data](#audio-data)
328
- - [Sample formats](#sample-formats)
329
- - [Event: 'deviceAdd'](#audio-event-deviceadd)
330
- - [Event: 'deviceRemove'](#audio-event-deviceremove)
331
- - [sdl.audio.bytesPerSample(format)](#sdlaudiobytespersampleformat)
332
- - [sdl.audio.minSampleValue(format)](#sdlaudiominsamplevalueformat)
333
- - [sdl.audio.maxSampleValue(format)](#sdlaudiomaxsamplevalueformat)
334
- - [sdl.audio.zeroSampleValue(format)](#sdlaudiozerosamplevalueformat)
335
- - [sdl.audio.readSample(format, buffer[, offset])](#sdlaudioreadsampleformat-buffer-offset)
336
- - [sdl.audio.writeSample(format, buffer, value[, offset])](#sdlaudiowritesampleformat-buffer-value-offset)
337
- - [sdl.audio.devices](#sdlaudiodevices)
338
- - [sdl.audio.openDevice(device[, options])](#sdlaudioopendevicedevice-options)
339
- - [class AudioInstance](#class-audioinstance)
340
- - [Event: 'close'](#audio-instance-event-close)
341
- - [audioInstance.id](#audioinstanceid)
342
- - [audioInstance.channels](#audioinstancechannels)
343
- - [audioInstance.frequency](#audioinstancefrequency)
344
- - [audioInstance.format](#audioinstanceformat)
345
- - [audioInstance.bytesPerSample](#audioinstancebytespersample)
346
- - [audioInstance.minSampleValue](#audioinstanceminsamplevalue)
347
- - [audioInstance.maxSampleValue](#audioinstancemaxsamplevalue)
348
- - [audioInstance.zeroSampleValue](#audioinstancezerosamplevalue)
349
- - [audioInstance.readSample(buffer[, offset])](#audioinstancereadsamplebuffer-offset)
350
- - [audioInstance.writeSample(buffer, value[, offset])](#audioinstancewritesamplebuffer-value-offset)
351
- - [audioInstance.buffered](#audioinstancebuffered)
352
- - [audioInstance.playing](#audioinstanceplaying)
353
- - [audioInstance.play([play])](#audioinstanceplayplay)
354
- - [audioInstance.pause()](#audioinstancepause)
355
- - [audioInstance.queued](#audioinstancequeued)
356
- - [audioInstance.clearQueue()](#audioinstanceclearqueue)
357
- - [audioInstance.closed](#audioinstanceclosed)
358
- - [audioInstance.close()](#audioinstanceclose)
359
- - [class AudioPlaybackInstance extends AudioInstance](#class-audioplaybackinstance-extends-audioinstance)
360
- - [playbackInstance.enqueue(buffer[, bytes])](#playbackinstanceenqueuebuffer-bytes)
361
- - [class AudioRecordingInstance extends AudioInstance](#class-audiorecordinginstance-extends-audioinstance)
362
- - [recordingInstance.dequeue(buffer[, bytes])](#recordinginstancedequeuebuffer-bytes)
363
- - [sdl.clipboard](#sdlclipboard)
364
- - [Event: 'update'](#clipboard-event-update)
365
- - [sdl.clipboard.text](#sdlclipboardtext)
366
- - [sdl.clipboard.setText(text)](#sdlclipboardsettexttext)
367
- - [sdl.power](#sdlpower)
368
- - [sdl.power.info](#sdlpowerinfo)
369
- - [helpers](#helpers)
370
-
371
- ## sdl
372
-
373
- ### sdl.info
374
-
375
- - `<object>`
376
- - `version: <object>`
377
- - `compile: <object>` The version of the SDL library that this package was compiled against.
378
- - `major, minor, patch: <Semver>` The components of the version.
379
- - `runtime: <object>` The version of the SDL library that was found and loaded at runtime.
380
- - `major, minor, patch: <Semver>` The components of the version.
381
- - `platform: <string>` The name of the platform we are running on. Possible values are: `'Linux'`, `'Windows'`, and `'Mac OS X'`.
382
- - `drivers: <object>`
383
- - `video: <object>`
384
- - `all: <string>[]` A list of all video drivers.
385
- - `current: <string>|<null>` The video driver that is currently selected.
386
- - `audio: <object>`
387
- - `all: <string>[]` A list of all audio drivers.
388
- - `current: <string>|<null>` The audio driver that is currently selected.
389
- - `initialized: <object>`
390
- - `video: <boolean>`: Is `true` if the video subsystem was successfully initialized, or `false` otherwise.
391
- - `audio: <boolean>`: Is `true` if the audio subsystem was successfully initialized, or `false` otherwise.
392
- - `joystick: <boolean>`: Is `true` if the joystick subsystem was successfully initialized, or `false` otherwise.
393
- - `controller: <boolean>`: Is `true` if the controller subsystem was successfully initialized, or `false` otherwise.
394
- - `haptic: <boolean>`: Is `true` if the haptic subsystem was successfully initialized, or `false` otherwise.
395
- - `sensor: <boolean>`: Is `true` if the sensor subsystem was successfully initialized, or `false` otherwise.
396
-
397
- The `sdl.info` object is filled with information produced during the initialization of SDL.
398
- All the values remain constant throughout the execution of the program.
399
-
400
- To initialize SDL with video/audio drivers other than the default ones, set the appropriate [environment variables](https://wiki.libsdl.org/FAQUsingSDL) to the desired value.
401
-
402
- Note that the `current` video or audio driver may be `null`.
403
- This usually happens on systems that don't have any compatible devices, such as on a CI pipeline.
404
-
405
- Sample data for Ubuntu:
406
-
407
- ```js
408
- {
409
- version: {
410
- compile: { major: 2, minor: 0, patch: 10 },
411
- runtime: { major: 2, minor: 0, patch: 10 },
412
- },
413
- platform: 'Linux',
414
- drivers: {
415
- video: {
416
- all: [ 'x11', 'wayland', 'dummy' ],
417
- current: 'x11',
418
- },
419
- audio: {
420
- all: [ 'pulseaudio', 'alsa', 'sndio', 'dsp', 'disk', 'dummy' ],
421
- current: 'pulseaudio',
422
- },
423
- },
424
- initialized: {
425
- video: true,
426
- audio: true,
427
- joystick: true,
428
- controller: true,
429
- haptic: true,
430
- sensor: true,
431
- },
432
- }
433
- ```
434
-
435
- ## sdl.video
436
-
437
- ### Image data
438
-
439
- There are 3 places in the API where you must provide an image to the library:
440
-
441
- - [`window.render()`](#windowrenderwidth-height-stride-format-buffer-options)
442
- - [`window.setIcon()`](#windowseticonwidth-height-stride-format-buffer)
443
- - [`mouse.setCursorImage()`](#sdlmousesetcursorimagewidth-height-stride-format-buffer-x-y)
444
-
445
- All three of these functions accept the image as a series of arguments:
446
-
447
- - `width: <number>` The width of the image in pixels.
448
- - `height: <number>` The height of the image in pixels.
449
- - `stride: <number>` How many bytes each row of the image takes up in the buffer. Usually equal to `width * bytesPerPixel`, but may be larger if the rows of the buffer are padded to always be some multiple of bytes.
450
- - `format: `[`<PixelFormat>`](#pixel-formats) The binary representation of the data in the buffer.
451
- - `buffer: <Buffer>` Holds the actual pixel data for the image, in the format and layout specified by all the above arguments.
452
-
453
- So, for example, to fill the window with a red+green gradient you could do:
454
-
455
- ```js
456
- const { pixelWidth: width, pixelHeight: height } = window
457
- const stride = width * 4
458
- const buffer = Buffer.alloc(stride * height)
459
-
460
- let offset = 0
461
- for (let i = 0; i < height; i++) {
462
- for (let j = 0; j < width; j++) {
463
- buffer[offset++] = Math.floor(256 * i / height) // R
464
- buffer[offset++] = Math.floor(256 * j / width) // G
465
- buffer[offset++] = 0 // B
466
- buffer[offset++] = 255 // A
467
- }
468
- }
469
-
470
- window.render(width, height, stride, 'rgba32', buffer)
471
- ```
472
-
473
- ### High-DPI
474
-
475
- On a high-dpi display, windows have more pixels than their `width` and `height` would indicate.
476
- On such systems `width` and `height` (and all other measurements such as `x` and `y`) are measured in "points" instead of pixels.
477
- Points are an abstract unit of measurement and don't necessarily correspond to pixels.
478
- If you need to work with pixels, you can use the window's `pixelWidth` and `pixelHeight` properties.
479
- You usually need these values when creating a "surface" that will be displayed on the window, such as a Buffer, Canvas, or 3D rendering viewport.
480
- I recommend that in these cases you always use `pixelWidth` and `pixelHeight`, since you don't know beforehand if your program will be running on a high-dpi system or not.
481
-
482
- ### Pixel formats
483
-
484
- String values used to represent how the pixels of an image are stored in a Buffer.
485
-
486
- | Value | Corresponding `SDL_PixelFormatEnum` | Comment |
487
- | --- | --- | --- |
488
- | `'rgb332'` | `SDL_PIXELFORMAT_RGB332` | |
489
- | `'rgb444'` | `SDL_PIXELFORMAT_RGB444` | |
490
- | `'rgb555'` | `SDL_PIXELFORMAT_RGB555` | |
491
- | `'bgr555'` | `SDL_PIXELFORMAT_BGR555` | |
492
- | `'argb4444'` | `SDL_PIXELFORMAT_ARGB4444` | |
493
- | `'rgba4444'` | `SDL_PIXELFORMAT_RGBA4444` | |
494
- | `'abgr4444'` | `SDL_PIXELFORMAT_ABGR4444` | |
495
- | `'bgra4444'` | `SDL_PIXELFORMAT_BGRA4444` | |
496
- | `'argb1555'` | `SDL_PIXELFORMAT_ARGB1555` | |
497
- | `'rgba5551'` | `SDL_PIXELFORMAT_RGBA5551` | |
498
- | `'abgr1555'` | `SDL_PIXELFORMAT_ABGR1555` | |
499
- | `'bgra5551'` | `SDL_PIXELFORMAT_BGRA5551` | |
500
- | `'rgb565'` | `SDL_PIXELFORMAT_RGB565` | |
501
- | `'bgr565'` | `SDL_PIXELFORMAT_BGR565` | |
502
- | `'rgb24'` | `SDL_PIXELFORMAT_RGB24` | |
503
- | `'bgr24'` | `SDL_PIXELFORMAT_BGR24` | |
504
- | `'rgb888'` | `SDL_PIXELFORMAT_RGB888` | |
505
- | `'rgbx8888'` | `SDL_PIXELFORMAT_RGBX8888` | |
506
- | `'bgr888'` | `SDL_PIXELFORMAT_BGR888` | |
507
- | `'bgrx8888'` | `SDL_PIXELFORMAT_BGRX8888` | |
508
- | `'argb8888'` | `SDL_PIXELFORMAT_ARGB8888` | |
509
- | `'rgba8888'` | `SDL_PIXELFORMAT_RGBA8888` | |
510
- | `'abgr8888'` | `SDL_PIXELFORMAT_ABGR8888` | |
511
- | `'bgra8888'` | `SDL_PIXELFORMAT_BGRA8888` | |
512
- | `'argb2101010'` | `SDL_PIXELFORMAT_ARGB2101010` | |
513
- | `'rgba32'` | `SDL_PIXELFORMAT_RGBA32` | alias for `'rgba8888'` on big endian machines and for `'abgr8888'` on little endian machines |
514
- | `'argb32'` | `SDL_PIXELFORMAT_ARGB32` | alias for `'argb8888'` on big endian machines and for `'bgra8888'` on little endian machines |
515
- | `'bgra32'` | `SDL_PIXELFORMAT_BGRA32` | alias for `'bgra8888'` on big endian machines and for `'argb8888'` on little endian machines |
516
- | `'abgr32'` | `SDL_PIXELFORMAT_ABGR32` | alias for `'abgr8888'` on big endian machines and for `'rgba8888'` on little endian machines |
517
- | `'yv12'` | `SDL_PIXELFORMAT_YV12` | planar mode: Y + V + U (3 planes) |
518
- | `'iyuv'` | `SDL_PIXELFORMAT_IYUV` | planar mode: Y + U + V (3 planes) |
519
- | `'yuy2'` | `SDL_PIXELFORMAT_YUY2` | packed mode: Y0+U0+Y1+V0 (1 plane) |
520
- | `'uyvy'` | `SDL_PIXELFORMAT_UYVY` | packed mode: U0+Y0+V0+Y1 (1 plane) |
521
- | `'yvyu'` | `SDL_PIXELFORMAT_YVYU` | packed mode: Y0+V0+Y1+U0 (1 plane) |
522
- | `'nv12'` | `SDL_PIXELFORMAT_NV12` | planar mode: Y + U/V interleaved (2 planes) |
523
- | `'nv21'` | `SDL_PIXELFORMAT_NV21` | planar mode: Y + V/U interleaved (2 planes) |
524
-
525
- ### Event: 'displayAdd'
526
-
527
- - `device: <object>`: An object from [`sdl.video.displays`](#sdlvideodisplays) indicating the display that caused the event.
528
-
529
- Fired when a display is added to the system.
530
- Check [`sdl.video.displays`](#sdlvideodisplays) to get the new list of displays.
531
-
532
- ### Event: 'displayRemove'
533
-
534
- - `device: <object>`: An object from [`sdl.video.displays`](#sdlvideodisplays) indicating the display that caused the event.
535
-
536
- Fired when a display is removed from the system.
537
- Check [`sdl.video.displays`](#sdlvideodisplays) to get the new list of displays.
538
-
539
- ### Event: 'displayOrient'
540
-
541
- - `device: <object>`: An object from [`sdl.video.displays`](#sdlvideodisplays) indicating the display that caused the event.
542
- - `orientation: <string>`: The display's new orientation.
543
-
544
- Fired when a display changes orientation.
545
-
546
- ### Event: 'displayMove'
547
-
548
- - `device: <object>`: An object from [`sdl.video.displays`](#sdlvideodisplays) indicating the display that caused the event.
549
-
550
- Fired when a display changes position.
551
-
552
- ### sdl.video.displays
553
-
554
- - `<object>[]`
555
- - `name: <string>|<null>` The name of the display, or `null` if it can't be determined.
556
- - `format: `[`<PixelFormat>`](#pixel-formats) The pixel format of the display.
557
- - `frequency: <number>` The refresh rate of the display.
558
- - `geometry: <object>` The desktop region represented by the display.
559
- - `x, y, width, height: <Rect>` The position and size of the display's geometry.
560
- - `usable: <object>` Similar to `geometry`, but excludes areas taken up by the OS or window manager such as menus, docks, e.t.c.
561
- - `x, y, width, height: <Rect>` The position and size of the display's usable region.
562
- - `dpi: <object>|<null>` Return pixel density for the display in dots/pixels-per-inch units. Might be `null` on some devices if DPI info can't be retrieved.
563
- - `horizontal: <number>` The horizontal density.
564
- - `vertical: <number>` The vertical density.
565
- - `diagonal: <number>` The diagonal density.
566
- - `orientation: <string>|<null>` The orientation of the display.
567
-
568
- A list of all detected displays.
569
-
570
- Possible values for `orientation` are `null` if it is unknown, or one of:
571
-
572
- | Value | Corresponding `SDL_DisplayOrientation` |
573
- | --- | --- |
574
- | `'landscape'` | `SDL_ORIENTATION_LANDSCAPE` |
575
- | `'landscapeFlipped'` | `SDL_ORIENTATION_LANDSCAPE_FLIPPED` |
576
- | `'portrait'` | `SDL_ORIENTATION_PORTRAIT` |
577
- | `'portraitFlipped'` | `SDL_ORIENTATION_PORTRAIT_FLIPPED` |
578
-
579
- Sample output for two side-to-side monitors is below.
580
- Notice how the geometries don't overlap:
581
-
582
- ```js
583
- [
584
- {
585
- name: '0',
586
- format: 'rgb888',
587
- frequency: 60,
588
- geometry: { x: 0, y: 0, width: 1920, height: 1080 },
589
- usable: { x: 0, y: 27, width: 1920, height: 1053 },
590
- dpi: { horizontal: 141.76, vertical: 142.13, diagonal: 141.85 },
591
- },
592
- {
593
- name: '1',
594
- format: 'rgb888',
595
- frequency: 60,
596
- geometry: { x: 1920, y: 0, width: 1920, height: 1080 },
597
- usable: { x: 1920, y: 27, width: 1920, height: 1053 },
598
- dpi: { horizontal: 141.76, vertical: 142.13, diagonal: 141.85 },
599
- },
600
- ]
601
- ```
602
-
603
- ### sdl.video.windows
604
-
605
- - [`<Window>`](#class-window)`[]`
606
-
607
- A list of all open windows.
608
-
609
- ### sdl.video.focused
610
-
611
- - [`<Window>`](#class-window)`|<null>`
612
-
613
- The window that has the current keyboard focus, or `null` if no window has the keyboard focus.
614
-
615
- ### sdl.video.hovered
616
-
617
- - [`<Window>`](#class-window)`|<null>`
618
-
619
- The window that the mouse is hovered over, or `null` if the mouse is not over a window.
620
-
621
- ### sdl.video.createWindow([options])
622
-
623
- - `options: <object>`
624
- - `title: <string>` Appears in the window's title bar. Default: `''`
625
- - `display: <number>` An object from `sdl.video.displays` to specify in which display the window should appear (if you have multiple displays). Default: `sdl.video.displays[0]`
626
- - `x: <number>` The x position in which the window should appear relative to the screen, or `null` for centered. Default: `null`
627
- - `y: <number>` The y position in which the window should appear relative to the screen, or `null` for centered. Default: `null`
628
- - `width: <number>` The width of the window. Default: `640`
629
- - `height: <number>` The height of the window. Default: `480`
630
- - `visible: <boolean>` Set to `false` to create a hidden window that will only be shown when you call [`window.show()`](#windowshowshow). Default: `true`
631
- - `fullscreen: <boolean>` Set to `true` to create the window in fullscreen mode. Default: `false`
632
- - `resizable: <boolean>` Set to `true` to allow resizing the window by dragging its borders. Default: `false`
633
- - `borderless: <boolean>` Set to `true` to completely hide the window's borders and title bar. Default: `false`
634
- - `alwaysOnTop: <boolean>` Set to `true` to always show the window above others. Default: `false`
635
- - `accelerated: <boolean>` Set to `false` to disable hardware accelerated rendering. Default: `true`
636
- - `vsync: <boolean>` Set to `false` to disable frame rate synchronization. Default: `true`
637
- - `opengl: <boolean>` Set to `true` to create an OpenGL-compatible window (for use with [@kmamal/gl](https://github.com/kmamal/headless-gl#readme)). Default: `false`
638
- - `webgpu: <boolean>` Set to `true` to create an WebGPU-compatible window (for use with [@kmamal/gpu](https://github.com/kmamal/gpu#readme)). Default: `false`
639
- - `skipTaskbar: <boolean>` X11 only. Set to `true` to not add the window to the taskbar. Default: `false`
640
- - `popupMenu: <boolean>` X11 only. Set to `true` to treat the window like a popup menu. Default: `false`
641
- - `tooltip: <boolean>` X11 only. Set to `true` to treat the window like a tooltip. Default: `false`
642
- - `utility: <boolean>` X11 only. Set to `true` to treat the window like a utility window. Default: `false`
643
- - Returns: [`<Window>`](#class-window) an object representing the new window.
644
-
645
- Creates a new window.
646
-
647
- The following restrictions apply:
648
-
649
- - The `display` option is mutually exclusive with the `x` and `y` options.
650
- - The `resizable` and `borderless` options are mutually exclusive.
651
- - The `opengl` and `webgpu` options are mutually exclusive.
652
- - The `vsync` option only applies to windows that are also `accelerated`.
653
- - The `accelerated` and `vsync` options have no effect if either `opengl` or `webgpu` is also specified.
654
-
655
- If you set the `opengl` or `webgpu` options, then you must use OpenGL/WebGPU calls to render to the window.
656
- Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-options) will fail.
657
-
658
- ## class Window
659
-
660
- The `Window` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
661
- Instead, objects returned by [`sdl.video.createWindow()`](#sdlvideocreatewindowoptions) are of type `Window`.
662
-
663
- ### Event: 'show'
664
-
665
- Fired when the window becomes visible.
666
-
667
- ### Event: 'hide'
668
-
669
- Fired when the window becomes hidden.
670
-
671
- ### Event: 'expose'
672
-
673
- Fired when the window becomes exposed and should be redrawn.
674
-
675
- ### Event: 'minimize'
676
-
677
- Fired when the window becomes minimized.
678
-
679
- ### Event: 'maximize'
680
-
681
- Fired when the window becomes maximized.
682
-
683
- ### Event: 'restore'
684
-
685
- Fired when the window gets restored.
686
-
687
- ### Event: 'move'
688
-
689
- - `x: <number>` The window's new x position, relative to the screen.
690
- - `y: <number>` The window's new y position, relative to the screen.
691
-
692
- Fired when the window changes position.
693
-
694
- ### Event: 'resize'
695
-
696
- - `width: <number>` The window's new width.
697
- - `height: <number>` The window's new height.
698
- - `pixelWidth: <number>` The window's new width in pixels. See [high-dpi](#high-dpi).
699
- - `pixelHeight: <number>` The window's new height in pixels. See [high-dpi](#high-dpi).
700
-
701
- Fired when the window changes size.
702
-
703
- ### Event: 'displayChange'
704
-
705
- - `display: <object>` An object from [`sdl.video.displays`](#sdlvideodisplays) indicating the window's new display.
706
-
707
- Fired when the window moves from one display to another.
708
-
709
- ### Event: 'focus'
710
-
711
- Fired when the window gains the keyboard focus.
712
-
713
- ### Event: 'blur'
714
-
715
- Fired when the window loses the keyboard focus.
716
-
717
- ### Event: 'hover'
718
-
719
- Fired when the mouse enters the window.
720
-
721
- ### Event: 'leave'
722
-
723
- Fired when the mouse leaves the window.
724
-
725
- ### Event: 'beforeClose'
726
-
727
- - `prevent: <function (void) => void>` Call this function to prevent the window from closing.
728
-
729
- Fired to indicate that the user requested that the window should close (usually by clicking the "x" button).
730
- If you need to display any confirmation dialogs, call `event.prevent()` and afterwards handle destruction manually.
731
- If `prevent` is not called, then the `beforeClose` event will be followed by a [`'close'`](#event-close) event.
732
-
733
- ### Event: 'close'
734
-
735
- Indicates that the window is about to be destroyed.
736
- Handle any cleanup here.
737
-
738
- ### Event: 'keyDown'
739
-
740
- - `scancode: `[`<Scancode>`](#enum-scancode) The scancode of the key that caused the event.
741
- - `key: `[`<Key>`](#virtual-keys)`|<null>` The virtual key that caused the event, or `null` if the physical key does not correspond to any virtual key.
742
- - `repeat: <boolean>` Is `true` if the event was generated by holding down a key for a long time.
743
- - `shift: <boolean>` Is `true` if the Shift key was pressed when the event was generated.
744
- - `ctrl: <boolean>` Is `true` if the Ctrl key was pressed when the event was generated.
745
- - `alt: <boolean>` Is `true` if the Alt key was pressed when the event was generated.
746
- - `super: <boolean>` Is `true` if the "Windows" key was pressed when the event was generated.
747
- - `altgr: <boolean>` Is `true` if the AltGr key was pressed when the event was generated.
748
- - `capslock: <boolean>` Is `true` if CapsLock was active when the event was generated.
749
- - `numlock: <boolean>` Is `true` if NumLock was active when the event was generated.
750
-
751
- Fired when a key is pressed, and will also be fired repeatedly afterwards if the key is held down.
752
-
753
- ### Event: 'keyUp'
754
-
755
- - `scancode: `[`<Scancode>`](#enum-scancode) The scancode of the key that caused the event.
756
- - `key: `[`<Key>`](#virtual-keys)`|<null>` The virtual key that caused the event, or `null` if the physical key does not correspond to any virtual key.
757
- - `shift: <boolean>` Is `true` if the Shift key was pressed when the event was generated.
758
- - `ctrl: <boolean>` Is `true` if the Ctrl key was pressed when the event was generated.
759
- - `alt: <boolean>` Is `true` if the Alt key was pressed when the event was generated.
760
- - `super: <boolean>` Is `true` if the "Windows" key was pressed when the event was generated.
761
- - `altgr: <boolean>` Is `true` if the AltGr key was pressed when the event was generated.
762
- - `capslock: <boolean>` Is `true` if CapsLock was active when the event was generated.
763
- - `numlock: <boolean>` Is `true` if NumLock was active when the event was generated.
764
-
765
- Fired when a key is released.
766
-
767
- ### Event: 'textInput'
768
-
769
- - `text: <string>` The unicode representation of the character that was entered.
770
-
771
- Fired when text is entered via the keyboard.
772
-
773
- ### Event: 'mouseButtonDown'
774
-
775
- - `x: <number>` The mouse's x position when the event happened, relative to the window.
776
- - `y: <number>` The mouse's y position when the event happened, relative to the window.
777
- - `touch: <boolean>` Is `true` if the event was caused by a touch event.
778
- - `button: `[`<sdl.mouse.BUTTON>`](#enum-button) The button that was pressed.
779
-
780
- Fired when a mouse button is pressed.
781
-
782
- ### Event: 'mouseButtonUp'
783
-
784
- - `x: <number>` The mouse's x position when the event happened, relative to the window.
785
- - `y: <number>` The mouse's y position when the event happened, relative to the window.
786
- - `touch: <boolean>` Is `true` if the event was caused by a touch event.
787
- - `button: `[`<sdl.mouse.BUTTON>`](#enum-button) The button that was released.
788
-
789
- Fired when a mouse button is released.
790
-
791
- ### Event: 'mouseMove'
792
-
793
- - `x: <number>` The mouse's x position when the event happened, relative to the window.
794
- - `y: <number>` The mouse's y position when the event happened, relative to the window.
795
- - `touch: <boolean>` Is `true` if the event was caused by a touch event.
796
-
797
- Fired when the mouse moves.
798
-
799
- ### Event: 'mouseWheel'
800
-
801
- - `x: <number>` The mouse's x position when the event happened, relative to the window.
802
- - `y: <number>` The mouse's y position when the event happened, relative to the window.
803
- - `touch: <boolean>` Is `true` if the event was caused by a touch event.
804
- - `dx: <number>` The wheel's x movement, relative to its last position.
805
- - `dy: <number>` The wheel's y movement, relative to its last position.
806
- - `flipped: <boolean>` Is `true` if the underlying platform reverses the mouse wheel's scroll direction. Multiply `dx` and `dy` by `-1` to get the correct values.
807
-
808
- Fired when the mouse wheel is scrolled.
809
-
810
- ### Event: 'fingerDown'
811
-
812
- - `device: <object>`: An object from [`sdl.touch.devices`](#sdltouchdevices) indicating the touch device that caused the event.
813
- - `fingerId: <number>` The id of the finger that coused the event.
814
- - `x: <number>` The finger's x position when the event happened, normalized in the range from `0` to `1`.
815
- - `y: <number>` The finger's y position when the event happened, normalized in the range from `0` to `1`.
816
- - `pressure: <number>` The finger's pressure when the event happened, normalized in the range from `0` to `1`.
817
- - `mouse: <boolean>` Is `true` if the event was caused by a mouse event.
818
-
819
- Fired when a finger is presed to the touch surface.
820
-
821
- ### Event: 'fingerUp'
822
-
823
- - `device: <object>`: An object from [`sdl.touch.devices`](#sdltouchdevices) indicating the touch device that caused the event.
824
- - `fingerId: <number>` The id of the finger that coused the event.
825
- - `x: <number>` The finger's x position when the event happened, normalized in the range from `0` to `1`.
826
- - `y: <number>` The finger's y position when the event happened, normalized in the range from `0` to `1`.
827
- - `pressure: <number>` The finger's pressure when the event happened, normalized in the range from `0` to `1`.
828
- - `mouse: <boolean>` Is `true` if the event was caused by a mouse event.
829
-
830
- Fired when a finger is lifted from the touch surface.
831
-
832
- ### Event: 'fingerMove'
833
-
834
- - `device: <object>`: An object from [`sdl.touch.devices`](#sdltouchdevices) indicating the touch device that caused the event.
835
- - `fingerId: <number>` The id of the finger that coused the event.
836
- - `x: <number>` The finger's x position when the event happened, normalized in the range from `0` to `1`.
837
- - `y: <number>` The finger's y position when the event happened, normalized in the range from `0` to `1`.
838
- - `dx: <number>` The finger's x position when the event happened, normalized in the range from `-1` to `1`.
839
- - `dy: <number>` The finger's y position when the event happened, normalized in the range from `-1` to `1`.
840
- - `pressure: <number>` The finger's pressure when the event happened, normalized in the range from `0` to `1`.
841
- - `mouse: <boolean>` Is `true` if the event was caused by a mouse event.
842
-
843
- Fired when a finger moves on the touch surface.
844
-
845
- ### Event: 'dropBegin'
846
-
847
- When you drop a set of items onto a window, first the [`'dropBegin'`](#event-dropbegin) event is fired, then a number of [`'dropText'`](#event-droptext) and/or [`'dropFile'`](#event-dropfile) events are fired, corresponding to the contents of the drop, then finally the [`'dropComplete'`](#event-dropcomplete) event is fired.
848
-
849
- ### Event: 'dropText'
850
-
851
- - `text: <string>`: The text that was dropped onto the window.
852
-
853
- Fired when one of the drops is a text item.
854
-
855
- ### Event: 'dropFile'
856
-
857
- - `file: <string>`: The path to the file that was dropped onto the window.
858
-
859
- Fired when one of the drops is a file.
860
-
861
- ### Event: 'dropComplete'
862
-
863
- Fired after a set of items has been dropped on a window.
864
-
865
- ### window.id
866
-
867
- - `<number>`
868
-
869
- A unique identifier for the window.
870
-
871
- ### window.title
872
-
873
- - `<string>`
874
-
875
- The text that appears in the window's title bar.
876
-
877
- ### window.setTitle(title)
878
-
879
- - `title: <string>`: The new title.
880
-
881
- Changes the text that appears in the window's title bar.
882
-
883
- ### window.x
884
-
885
- - `<number>`
886
-
887
- The window's x position, relative to the screen.
888
-
889
- ### window.y
890
-
891
- - `<number>`
892
-
893
- The window's y position, relative to the screen.
894
-
895
- ### window.setPosition(x, y)
896
-
897
- - `x: <number>`: The new x position, relative to the screen.
898
- - `y: <number>`: The new y position, relative to the screen.
899
-
900
- Moves the window to a new position on the screen.
901
-
902
- ### window.width
903
-
904
- - `<number>`
905
-
906
- The window's width.
907
-
908
- ### window.height
909
-
910
- - `<number>`
911
-
912
- The window's height.
913
-
914
- ### window.pixelWidth
915
-
916
- - `<number>`
917
-
918
- The window's width in pixels.
919
- Is larger than [`width`](#windowwidth) on [high-dpi](#high-dpi) displays.
920
-
921
- ### window.pixelHeight
922
-
923
- - `<number>`
924
-
925
- The window's height in pixels.
926
- Is larger than [`height`](#windowheight) on [high-dpi](#high-dpi) displays.
927
-
928
- ### window.setSize(width, height)
929
-
930
- - `width: <number>`: The new width.
931
- - `height: <number>`: The new height.
932
-
933
- Changes the size of the window.
934
-
935
- ### window.setSizeInPixels(pixelWidth, pixelHeight)
936
-
937
- - `pixelWidth: <number>`: The new width in pixels.
938
- - `pixelHeight: <number>`: The new height in pixels.
939
-
940
- Changes the size of the window.
941
- This function only behaves differently from [`window.setSize()`](#windowsetsizewidth-height) for [high-dpi](#high-dpi) displays.
942
-
943
- ### window.display
944
-
945
- - `<object>`
946
-
947
- An object from [`sdl.video.displays`](#sdlvideodisplays) indicating the display the window belongs to.
948
- If the window spans multiple displays, then the display that contains the center of the window is returned.
949
-
950
- ### window.visible
951
-
952
- - `<boolean>`
953
-
954
- Is `true` if the window is visible.
955
-
956
- ### window.show([show])
957
-
958
- - `show: <boolean>` Set to `true` to make the window visible, `false` to hide it. Default: `true`
959
-
960
- Shows or hides the window.
961
-
962
- ### window.hide()
963
-
964
- Equivalent to [`window.show(false)`](#windowshowshow).
965
-
966
- ### window.fullscreen
967
-
968
- - `<boolean>`
969
-
970
- Is `true` if the window is fullscreen.
971
- A fullscreen window is displayed over the entire screen.
972
-
973
- ### window.setFullscreen(fullscreen)
974
-
975
- - `fullscreen: <boolean>` The new value of the property.
976
-
977
- Changes the window's fullscreen property.
978
-
979
- ### window.resizable
980
-
981
- - `<boolean>`
982
-
983
- Is `true` if the window is resizable.
984
- A resizable window can be resized by dragging its borders.
985
-
986
- ### window.setResizable(resizable)
987
-
988
- - `resizable: <boolean>` The new value of the property.
989
-
990
- Changes the window's resizable property.
991
-
992
- ### window.borderless
993
-
994
- - `<boolean>`
995
-
996
- Is `true` if the window is borderless.
997
- A borderless window has no borders or title bar.
998
-
999
- ### window.setBorderless(borderless)
1000
-
1001
- - `borderless: <boolean>` The new value of the property.
1002
-
1003
- Changes the window's borderless property.
1004
-
1005
- ### window.alwaysOnTop
1006
-
1007
- - `<boolean>`
1008
-
1009
- Is `true` if the window was created with `alwaysOnTop: true`.
1010
- Such a window is always be shown above other windows.
1011
-
1012
- ### window.accelerated
1013
-
1014
- - `<boolean>`
1015
-
1016
- Is `true` if the window is using hardware accelerated rendering.
1017
-
1018
- ### window.setAccelerated(accelerated)
1019
-
1020
- - `accelerated: <boolean>` The new value of the property.
1021
-
1022
- Changes the window's accelerated property.
1023
-
1024
- If you have set the `opengl` or `webgpu` options, then calls to this function will fail.
1025
-
1026
- ### window.vsync
1027
-
1028
- - `<boolean>`
1029
-
1030
- Is `true` if the window is using vsync.
1031
- Vsync synchronizes the window's frame rate with the display's refresh rate to prevent tearing.
1032
- Note that vsync can only be set to `true` if [`accelerated`](#windowaccelerated) is also `true`.
1033
-
1034
- ### window.setVsync(vsync)
1035
-
1036
- - `vsync: <boolean>` The new value of the property.
1037
-
1038
- Changes the window's vsync property.
1039
-
1040
- If you have set the `opengl` or `webgpu` options, then calls to this function will fail.
1041
-
1042
- ### window.opengl
1043
-
1044
- - `<boolean>`
1045
-
1046
- Is `true` if the window was created in OpenGl mode.
1047
- In OpenGL mode, you must use OpenGL calls to render to the window.
1048
- Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-options) will fail.
1049
-
1050
- ### window.webgpu
1051
-
1052
- - `<boolean>`
1053
-
1054
- Is `true` if the window was created in WebGPU mode.
1055
- In WebGPU mode, you must use WebGPU calls to render to the window.
1056
- Calls to [`render()`](#windowrenderwidth-height-stride-format-buffer-options) will fail.
1057
-
1058
- ### window.native
1059
-
1060
- - `<object>`
1061
- - `handle : <Buffer>|<null>` The platform-specific handle of the window, or `null` if it can't be determined.
1062
-
1063
- The native type of `handle` is HWND on Windows, NSView* on macOS, and Window (unsigned long) on Linux.
1064
- It should work exactly like the [`win.getNativeWindowHandle()`](https://www.electronjs.org/docs/latest/api/browser-window#wingetnativewindowhandle) electron method.
1065
-
1066
- The `window.native` object might also sometimes include extra fields other than the ones documented here.
1067
- Please ignore and do not use these.
1068
- They are used internally for passing to [@kmamal/gl](https://github.com/kmamal/headless-gl#readme) or [@kmamal/gpu](https://github.com/kmamal/gpu#readme) and can change at any time.
1069
-
1070
- ### window.maximized
1071
-
1072
- - `<boolean>`
1073
-
1074
- Is `true` if the window is maximized.
1075
-
1076
- ### window.maximize()
1077
-
1078
- Maximizes the window.
1079
-
1080
- ### window.minimized
1081
-
1082
- - `<boolean>`
1083
-
1084
- Is `true` if the window is minimized.
1085
-
1086
- ### window.minimize()
1087
-
1088
- Minimizes the window.
1089
-
1090
- ### window.restore()
1091
-
1092
- Restores the window so it is neither minimized nor maximized.
1093
-
1094
- ### window.focused
1095
-
1096
- - `<boolean>`
1097
-
1098
- Is `true` if the window has keyboard input.
1099
-
1100
- ### window.focus()
1101
-
1102
- Gives the window the keyboard focus.
1103
-
1104
- ### window.hovered
1105
-
1106
- - `<boolean>`
1107
-
1108
- Is `true` if the mouse is over the window.
1109
-
1110
- ### window.skipTaskbar
1111
-
1112
- - `<boolean>`
1113
-
1114
- X11 only.
1115
- Is `true` if the window was created with `skipTaskbar: true`.
1116
- Such a window is not added to the taskbar.
1117
-
1118
- ### window.popupMenu
1119
-
1120
- - `<boolean>`
1121
-
1122
- X11 only.
1123
- Is `true` if the window was created with `popupMenu: true`.
1124
- Such a window is always treated as a popup menu.
1125
-
1126
- ### window.tooltip
1127
-
1128
- - `<boolean>`
1129
-
1130
- X11 only.
1131
- Is `true` if the window was created with `tooltip: true`.
1132
- Such a window is always treated as a tooltip.
1133
-
1134
- ### window.utility
1135
-
1136
- - `<boolean>`
1137
-
1138
- X11 only.
1139
- Is `true` if the window was created with `utility: true`.
1140
- Such a window is always treated as a utility window.
1141
-
1142
- ### window.render(width, height, stride, format, buffer[, options])
1143
-
1144
- - `width, height, stride, format, buffer: `[`<Image>`](#image-data) The image to display on the window.
1145
- - `options: <object>`
1146
- - `scaling: <string>` How to scale the image to match the window size. Default: `'nearest'`
1147
- - `dstRect: <object>` Where exactly on the window to draw the image. Default: whole window.
1148
- - `x, y, width, height: <rect>` The components of the rectangle.
1149
-
1150
- Displays an image in the window.
1151
-
1152
- By default the image is displayed over the entire surface of the window.
1153
- You may pass the optional `dstRect` parameter to set where exactly on the window to display the image.
1154
- The rest of the window will be filled with black.
1155
-
1156
- If the dimensions of the image do not match the dimensions of the area it should be displayed in, then the image will be stretched to match.
1157
- The `scaling` argument controls how exactly the scaling is implemented.
1158
- Possible values are:
1159
-
1160
- | Value | Corresponding `SDL_ScaleMode` | Description |
1161
- | --- | --- | --- |
1162
- | `'nearest'` | `SDL_ScaleModeNearest` | nearest pixel sampling |
1163
- | `'linear'` | `SDL_ScaleModeLinear` | linear filtering |
1164
- | `'best'` | `SDL_ScaleModeBest` | anisotropic filtering |
1165
-
1166
- If the window was created with either of the `opengl` or `webgpu` options, then you must use OpenGL/WebGPU calls to render to the window.
1167
- Calls to `render()` will fail.
1168
-
1169
- ### window.setIcon(width, height, stride, format, buffer)
1170
-
1171
- - `width, height, stride, format, buffer: `[`<Image>`](#image-data) The image to display as the icon of the window.
1172
-
1173
- Set's the window's icon, usually displayed in the title bar and the taskbar.
1174
-
1175
- ### window.flash([untilFocused])
1176
-
1177
- - `untilFocused: <boolean>` Whether to keep flashing the window until the user focuses it. Default: `false`
1178
-
1179
- Flash the window briefly to get attention.
1180
- If `untilFocused` is set, the window will continue flashing until the user focuses it.
1181
-
1182
- ### window.stopFlashing()
1183
-
1184
- Stop the window from flashing.
1185
-
1186
- ### window.destroyed
1187
-
1188
- - `<boolean>`
1189
-
1190
- Is `true` if the window is destroyed.
1191
- A destroyed window object must not be used any further.
1192
-
1193
- ### window.destroy()
1194
-
1195
- Destroys the window.
1196
-
1197
- ### window.destroyGently()
1198
-
1199
- Asks before destroying the window.
1200
- The difference between this function and [destroy()](#windowdestroy) is that this function first makes the window emit the [`'beforeClose'`](#event-beforeclose) event, giving you a chance to prevent the window from being destroyed.
1201
-
1202
- ## sdl.keyboard
1203
-
1204
- 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).
1205
-
1206
- On the physical level, each of the physical keys corresponds to a number: the key's scancode.
1207
- For any given keyboard, the same key will always produce the same scancode.
1208
- 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.
1209
-
1210
- 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.
1211
-
1212
- More commonly, you don't care about the physical key itself but about the "meaning" associated with each key:
1213
- the character that it produces ("a", "b", "@", " ", .e.t.c.) or the function that it corresponds to ("Esc", "F4", "Ctrl", e.t.c.).
1214
- Your operating system provides a "keyboard mapping" that associates physical keys with their corresponding meaning.
1215
- 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).
1216
- These meanings are represented as [virtual key strings](#virtual-keys).
1217
- 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.
1218
-
1219
- Note that not all physical keys correspond to a well-defined meaning and thus don't have a virtual key value associated with them.
1220
- The key events for these keys will have a `null` value for the `key` property.
1221
-
1222
- But sometimes the application doesn't care about individual keys at all, but about the resulting text that the user is entering.
1223
- 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.
1224
- Trying to handle text input by manually translating key presses to text is not a very viable solution.
1225
- 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.
1226
-
1227
- ### Virtual keys
1228
-
1229
- String values used to represent virtual keys in the context of the current keyboard mapping.
1230
- Note that some keys do not correspond to any virtual key.
1231
- A Key can be either one of the values below __or__ any unicode character.
1232
- Keys that produce characters are represented by that character.
1233
- All others are represented by one of these values:
1234
-
1235
- `'&&'`, `'+/-'`, `'||'`, `'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'`.
1236
-
1237
- ### Enum: SCANCODE
1238
-
1239
- Used to represent physical keys on the keyboard.
1240
- The same key will always produce the same scancode.
1241
- Values are based on the [USB usage page standard](https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf).
1242
-
1243
- <details>
1244
-
1245
- <summary>Click to expand table</summary>
1246
-
1247
- | Value | Corresponding `SDL_Scancode` | Comment |
1248
- | --- | --- | --- |
1249
- | `sdl.keyboard.SCANCODE.A` | `SDL_SCANCODE_A` | |
1250
- | `sdl.keyboard.SCANCODE.B` | `SDL_SCANCODE_B` | |
1251
- | `sdl.keyboard.SCANCODE.C` | `SDL_SCANCODE_C` | |
1252
- | `sdl.keyboard.SCANCODE.D` | `SDL_SCANCODE_D` | |
1253
- | `sdl.keyboard.SCANCODE.E` | `SDL_SCANCODE_E` | |
1254
- | `sdl.keyboard.SCANCODE.F` | `SDL_SCANCODE_F` | |
1255
- | `sdl.keyboard.SCANCODE.G` | `SDL_SCANCODE_G` | |
1256
- | `sdl.keyboard.SCANCODE.H` | `SDL_SCANCODE_H` | |
1257
- | `sdl.keyboard.SCANCODE.I` | `SDL_SCANCODE_I` | |
1258
- | `sdl.keyboard.SCANCODE.J` | `SDL_SCANCODE_J` | |
1259
- | `sdl.keyboard.SCANCODE.K` | `SDL_SCANCODE_K` | |
1260
- | `sdl.keyboard.SCANCODE.L` | `SDL_SCANCODE_L` | |
1261
- | `sdl.keyboard.SCANCODE.M` | `SDL_SCANCODE_M` | |
1262
- | `sdl.keyboard.SCANCODE.N` | `SDL_SCANCODE_N` | |
1263
- | `sdl.keyboard.SCANCODE.O` | `SDL_SCANCODE_O` | |
1264
- | `sdl.keyboard.SCANCODE.P` | `SDL_SCANCODE_P` | |
1265
- | `sdl.keyboard.SCANCODE.Q` | `SDL_SCANCODE_Q` | |
1266
- | `sdl.keyboard.SCANCODE.R` | `SDL_SCANCODE_R` | |
1267
- | `sdl.keyboard.SCANCODE.S` | `SDL_SCANCODE_S` | |
1268
- | `sdl.keyboard.SCANCODE.T` | `SDL_SCANCODE_T` | |
1269
- | `sdl.keyboard.SCANCODE.U` | `SDL_SCANCODE_U` | |
1270
- | `sdl.keyboard.SCANCODE.V` | `SDL_SCANCODE_V` | |
1271
- | `sdl.keyboard.SCANCODE.W` | `SDL_SCANCODE_W` | |
1272
- | `sdl.keyboard.SCANCODE.X` | `SDL_SCANCODE_X` | |
1273
- | `sdl.keyboard.SCANCODE.Y` | `SDL_SCANCODE_Y` | |
1274
- | `sdl.keyboard.SCANCODE.Z` | `SDL_SCANCODE_Z` | |
1275
- | `sdl.keyboard.SCANCODE.1` | `SDL_SCANCODE_1` | |
1276
- | `sdl.keyboard.SCANCODE.2` | `SDL_SCANCODE_2` | |
1277
- | `sdl.keyboard.SCANCODE.3` | `SDL_SCANCODE_3` | |
1278
- | `sdl.keyboard.SCANCODE.4` | `SDL_SCANCODE_4` | |
1279
- | `sdl.keyboard.SCANCODE.5` | `SDL_SCANCODE_5` | |
1280
- | `sdl.keyboard.SCANCODE.6` | `SDL_SCANCODE_6` | |
1281
- | `sdl.keyboard.SCANCODE.7` | `SDL_SCANCODE_7` | |
1282
- | `sdl.keyboard.SCANCODE.8` | `SDL_SCANCODE_8` | |
1283
- | `sdl.keyboard.SCANCODE.9` | `SDL_SCANCODE_9` | |
1284
- | `sdl.keyboard.SCANCODE.0` | `SDL_SCANCODE_0` | |
1285
- | `sdl.keyboard.SCANCODE.RETURN` | `SDL_SCANCODE_RETURN` | |
1286
- | `sdl.keyboard.SCANCODE.ESCAPE` | `SDL_SCANCODE_ESCAPE` | |
1287
- | `sdl.keyboard.SCANCODE.BACKSPACE` | `SDL_SCANCODE_BACKSPACE` | |
1288
- | `sdl.keyboard.SCANCODE.TAB` | `SDL_SCANCODE_TAB` | |
1289
- | `sdl.keyboard.SCANCODE.SPACE` | `SDL_SCANCODE_SPACE` | |
1290
- | `sdl.keyboard.SCANCODE.MINUS` | `SDL_SCANCODE_MINUS` | |
1291
- | `sdl.keyboard.SCANCODE.EQUALS` | `SDL_SCANCODE_EQUALS` | |
1292
- | `sdl.keyboard.SCANCODE.LEFTBRACKET` | `SDL_SCANCODE_LEFTBRACKET` | |
1293
- | `sdl.keyboard.SCANCODE.RIGHTBRACKET` | `SDL_SCANCODE_RIGHTBRACKET` | |
1294
- | `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. |
1295
- | `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. |
1296
- | `sdl.keyboard.SCANCODE.SEMICOLON` | `SDL_SCANCODE_SEMICOLON` | |
1297
- | `sdl.keyboard.SCANCODE.APOSTROPHE` | `SDL_SCANCODE_APOSTROPHE` | |
1298
- | `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. |
1299
- | `sdl.keyboard.SCANCODE.COMMA` | `SDL_SCANCODE_COMMA` | |
1300
- | `sdl.keyboard.SCANCODE.PERIOD` | `SDL_SCANCODE_PERIOD` | |
1301
- | `sdl.keyboard.SCANCODE.SLASH` | `SDL_SCANCODE_SLASH` | |
1302
- | `sdl.keyboard.SCANCODE.CAPSLOCK` | `SDL_SCANCODE_CAPSLOCK` | |
1303
- | `sdl.keyboard.SCANCODE.F1` | `SDL_SCANCODE_F1` | |
1304
- | `sdl.keyboard.SCANCODE.F2` | `SDL_SCANCODE_F2` | |
1305
- | `sdl.keyboard.SCANCODE.F3` | `SDL_SCANCODE_F3` | |
1306
- | `sdl.keyboard.SCANCODE.F4` | `SDL_SCANCODE_F4` | |
1307
- | `sdl.keyboard.SCANCODE.F5` | `SDL_SCANCODE_F5` | |
1308
- | `sdl.keyboard.SCANCODE.F6` | `SDL_SCANCODE_F6` | |
1309
- | `sdl.keyboard.SCANCODE.F7` | `SDL_SCANCODE_F7` | |
1310
- | `sdl.keyboard.SCANCODE.F8` | `SDL_SCANCODE_F8` | |
1311
- | `sdl.keyboard.SCANCODE.F9` | `SDL_SCANCODE_F9` | |
1312
- | `sdl.keyboard.SCANCODE.F10` | `SDL_SCANCODE_F10` | |
1313
- | `sdl.keyboard.SCANCODE.F11` | `SDL_SCANCODE_F11` | |
1314
- | `sdl.keyboard.SCANCODE.F12` | `SDL_SCANCODE_F12` | |
1315
- | `sdl.keyboard.SCANCODE.PRINTSCREEN` | `SDL_SCANCODE_PRINTSCREEN` | |
1316
- | `sdl.keyboard.SCANCODE.SCROLLLOCK` | `SDL_SCANCODE_SCROLLLOCK` | |
1317
- | `sdl.keyboard.SCANCODE.PAUSE` | `SDL_SCANCODE_PAUSE` | |
1318
- | `sdl.keyboard.SCANCODE.INSERT` | `SDL_SCANCODE_INSERT` | insert on PC, help on some Mac keyboards |
1319
- | `sdl.keyboard.SCANCODE.HOME` | `SDL_SCANCODE_HOME` | |
1320
- | `sdl.keyboard.SCANCODE.PAGEUP` | `SDL_SCANCODE_PAGEUP` | |
1321
- | `sdl.keyboard.SCANCODE.DELETE` | `SDL_SCANCODE_DELETE` | |
1322
- | `sdl.keyboard.SCANCODE.END` | `SDL_SCANCODE_END` | |
1323
- | `sdl.keyboard.SCANCODE.PAGEDOWN` | `SDL_SCANCODE_PAGEDOWN` | |
1324
- | `sdl.keyboard.SCANCODE.RIGHT` | `SDL_SCANCODE_RIGHT` | |
1325
- | `sdl.keyboard.SCANCODE.LEFT` | `SDL_SCANCODE_LEFT` | |
1326
- | `sdl.keyboard.SCANCODE.DOWN` | `SDL_SCANCODE_DOWN` | |
1327
- | `sdl.keyboard.SCANCODE.UP` | `SDL_SCANCODE_UP` | |
1328
- | `sdl.keyboard.SCANCODE.NUMLOCKCLEAR` | `SDL_SCANCODE_NUMLOCKCLEAR` | num lock on PC, clear on Mac keyboards |
1329
- | `sdl.keyboard.SCANCODE.KP_DIVIDE` | `SDL_SCANCODE_KP_DIVIDE` | |
1330
- | `sdl.keyboard.SCANCODE.KP_MULTIPLY` | `SDL_SCANCODE_KP_MULTIPLY` | |
1331
- | `sdl.keyboard.SCANCODE.KP_MINUS` | `SDL_SCANCODE_KP_MINUS` | |
1332
- | `sdl.keyboard.SCANCODE.KP_PLUS` | `SDL_SCANCODE_KP_PLUS` | |
1333
- | `sdl.keyboard.SCANCODE.KP_ENTER` | `SDL_SCANCODE_KP_ENTER` | |
1334
- | `sdl.keyboard.SCANCODE.KP_1` | `SDL_SCANCODE_KP_1` | |
1335
- | `sdl.keyboard.SCANCODE.KP_2` | `SDL_SCANCODE_KP_2` | |
1336
- | `sdl.keyboard.SCANCODE.KP_3` | `SDL_SCANCODE_KP_3` | |
1337
- | `sdl.keyboard.SCANCODE.KP_4` | `SDL_SCANCODE_KP_4` | |
1338
- | `sdl.keyboard.SCANCODE.KP_5` | `SDL_SCANCODE_KP_5` | |
1339
- | `sdl.keyboard.SCANCODE.KP_6` | `SDL_SCANCODE_KP_6` | |
1340
- | `sdl.keyboard.SCANCODE.KP_7` | `SDL_SCANCODE_KP_7` | |
1341
- | `sdl.keyboard.SCANCODE.KP_8` | `SDL_SCANCODE_KP_8` | |
1342
- | `sdl.keyboard.SCANCODE.KP_9` | `SDL_SCANCODE_KP_9` | |
1343
- | `sdl.keyboard.SCANCODE.KP_0` | `SDL_SCANCODE_KP_0` | |
1344
- | `sdl.keyboard.SCANCODE.KP_PERIOD` | `SDL_SCANCODE_KP_PERIOD` | |
1345
- | `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. |
1346
- | `sdl.keyboard.SCANCODE.APPLICATION` | `SDL_SCANCODE_APPLICATION` | windows contextual menu, compose |
1347
- | `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. |
1348
- | `sdl.keyboard.SCANCODE.KP_EQUALS` | `SDL_SCANCODE_KP_EQUALS` | |
1349
- | `sdl.keyboard.SCANCODE.F13` | `SDL_SCANCODE_F13` | |
1350
- | `sdl.keyboard.SCANCODE.F14` | `SDL_SCANCODE_F14` | |
1351
- | `sdl.keyboard.SCANCODE.F15` | `SDL_SCANCODE_F15` | |
1352
- | `sdl.keyboard.SCANCODE.F16` | `SDL_SCANCODE_F16` | |
1353
- | `sdl.keyboard.SCANCODE.F17` | `SDL_SCANCODE_F17` | |
1354
- | `sdl.keyboard.SCANCODE.F18` | `SDL_SCANCODE_F18` | |
1355
- | `sdl.keyboard.SCANCODE.F19` | `SDL_SCANCODE_F19` | |
1356
- | `sdl.keyboard.SCANCODE.F20` | `SDL_SCANCODE_F20` | |
1357
- | `sdl.keyboard.SCANCODE.F21` | `SDL_SCANCODE_F21` | |
1358
- | `sdl.keyboard.SCANCODE.F22` | `SDL_SCANCODE_F22` | |
1359
- | `sdl.keyboard.SCANCODE.F23` | `SDL_SCANCODE_F23` | |
1360
- | `sdl.keyboard.SCANCODE.F24` | `SDL_SCANCODE_F24` | |
1361
- | `sdl.keyboard.SCANCODE.EXECUTE` | `SDL_SCANCODE_EXECUTE` | |
1362
- | `sdl.keyboard.SCANCODE.HELP` | `SDL_SCANCODE_HELP` | |
1363
- | `sdl.keyboard.SCANCODE.MENU` | `SDL_SCANCODE_MENU` | |
1364
- | `sdl.keyboard.SCANCODE.SELECT` | `SDL_SCANCODE_SELECT` | |
1365
- | `sdl.keyboard.SCANCODE.STOP` | `SDL_SCANCODE_STOP` | |
1366
- | `sdl.keyboard.SCANCODE.AGAIN` | `SDL_SCANCODE_AGAIN` | redo |
1367
- | `sdl.keyboard.SCANCODE.UNDO` | `SDL_SCANCODE_UNDO` | |
1368
- | `sdl.keyboard.SCANCODE.CUT` | `SDL_SCANCODE_CUT` | |
1369
- | `sdl.keyboard.SCANCODE.COPY` | `SDL_SCANCODE_COPY` | |
1370
- | `sdl.keyboard.SCANCODE.PASTE` | `SDL_SCANCODE_PASTE` | |
1371
- | `sdl.keyboard.SCANCODE.FIND` | `SDL_SCANCODE_FIND` | |
1372
- | `sdl.keyboard.SCANCODE.MUTE` | `SDL_SCANCODE_MUTE` | |
1373
- | `sdl.keyboard.SCANCODE.VOLUMEUP` | `SDL_SCANCODE_VOLUMEUP` | |
1374
- | `sdl.keyboard.SCANCODE.VOLUMEDOWN` | `SDL_SCANCODE_VOLUMEDOWN` | |
1375
- | `sdl.keyboard.SCANCODE.KP_COMMA` | `SDL_SCANCODE_KP_COMMA` | |
1376
- | `sdl.keyboard.SCANCODE.KP_EQUALSAS400` | `SDL_SCANCODE_KP_EQUALSAS400` | |
1377
- | `sdl.keyboard.SCANCODE.INTERNATIONAL1` | `SDL_SCANCODE_INTERNATIONAL1` | used on Asian keyboards, see footnotes in USB doc |
1378
- | `sdl.keyboard.SCANCODE.INTERNATIONAL2` | `SDL_SCANCODE_INTERNATIONAL2` | |
1379
- | `sdl.keyboard.SCANCODE.INTERNATIONAL3` | `SDL_SCANCODE_INTERNATIONAL3` | Yen |
1380
- | `sdl.keyboard.SCANCODE.INTERNATIONAL4` | `SDL_SCANCODE_INTERNATIONAL4` | |
1381
- | `sdl.keyboard.SCANCODE.INTERNATIONAL5` | `SDL_SCANCODE_INTERNATIONAL5` | |
1382
- | `sdl.keyboard.SCANCODE.INTERNATIONAL6` | `SDL_SCANCODE_INTERNATIONAL6` | |
1383
- | `sdl.keyboard.SCANCODE.INTERNATIONAL7` | `SDL_SCANCODE_INTERNATIONAL7` | |
1384
- | `sdl.keyboard.SCANCODE.INTERNATIONAL8` | `SDL_SCANCODE_INTERNATIONAL8` | |
1385
- | `sdl.keyboard.SCANCODE.INTERNATIONAL9` | `SDL_SCANCODE_INTERNATIONAL9` | |
1386
- | `sdl.keyboard.SCANCODE.LANG1` | `SDL_SCANCODE_LANG1` | Hangul/English toggle |
1387
- | `sdl.keyboard.SCANCODE.LANG2` | `SDL_SCANCODE_LANG2` | Hanja conversion |
1388
- | `sdl.keyboard.SCANCODE.LANG3` | `SDL_SCANCODE_LANG3` | Katakana |
1389
- | `sdl.keyboard.SCANCODE.LANG4` | `SDL_SCANCODE_LANG4` | Hiragana |
1390
- | `sdl.keyboard.SCANCODE.LANG5` | `SDL_SCANCODE_LANG5` | Zenkaku/Hankaku |
1391
- | `sdl.keyboard.SCANCODE.LANG6` | `SDL_SCANCODE_LANG6` | |
1392
- | `sdl.keyboard.SCANCODE.LANG7` | `SDL_SCANCODE_LANG7` | |
1393
- | `sdl.keyboard.SCANCODE.LANG8` | `SDL_SCANCODE_LANG8` | |
1394
- | `sdl.keyboard.SCANCODE.LANG9` | `SDL_SCANCODE_LANG9` | |
1395
- | `sdl.keyboard.SCANCODE.ALTERASE` | `SDL_SCANCODE_ALTERASE` | Erase-Eaze |
1396
- | `sdl.keyboard.SCANCODE.SYSREQ` | `SDL_SCANCODE_SYSREQ` | |
1397
- | `sdl.keyboard.SCANCODE.CANCEL` | `SDL_SCANCODE_CANCEL` | |
1398
- | `sdl.keyboard.SCANCODE.CLEAR` | `SDL_SCANCODE_CLEAR` | |
1399
- | `sdl.keyboard.SCANCODE.PRIOR` | `SDL_SCANCODE_PRIOR` | |
1400
- | `sdl.keyboard.SCANCODE.RETURN2` | `SDL_SCANCODE_RETURN2` | |
1401
- | `sdl.keyboard.SCANCODE.SEPARATOR` | `SDL_SCANCODE_SEPARATOR` | |
1402
- | `sdl.keyboard.SCANCODE.OUT` | `SDL_SCANCODE_OUT` | |
1403
- | `sdl.keyboard.SCANCODE.OPER` | `SDL_SCANCODE_OPER` | |
1404
- | `sdl.keyboard.SCANCODE.CLEARAGAIN` | `SDL_SCANCODE_CLEARAGAIN` | |
1405
- | `sdl.keyboard.SCANCODE.CRSEL` | `SDL_SCANCODE_CRSEL` | |
1406
- | `sdl.keyboard.SCANCODE.EXSEL` | `SDL_SCANCODE_EXSEL` | |
1407
- | `sdl.keyboard.SCANCODE.KP_00` | `SDL_SCANCODE_KP_00` | |
1408
- | `sdl.keyboard.SCANCODE.KP_000` | `SDL_SCANCODE_KP_000` | |
1409
- | `sdl.keyboard.SCANCODE.THOUSANDSSEPARATOR` | `SDL_SCANCODE_THOUSANDSSEPARATOR` | |
1410
- | `sdl.keyboard.SCANCODE.DECIMALSEPARATOR` | `SDL_SCANCODE_DECIMALSEPARATOR` | |
1411
- | `sdl.keyboard.SCANCODE.CURRENCYUNIT` | `SDL_SCANCODE_CURRENCYUNIT` | |
1412
- | `sdl.keyboard.SCANCODE.CURRENCYSUBUNIT` | `SDL_SCANCODE_CURRENCYSUBUNIT` | |
1413
- | `sdl.keyboard.SCANCODE.KP_LEFTPAREN` | `SDL_SCANCODE_KP_LEFTPAREN` | |
1414
- | `sdl.keyboard.SCANCODE.KP_RIGHTPAREN` | `SDL_SCANCODE_KP_RIGHTPAREN` | |
1415
- | `sdl.keyboard.SCANCODE.KP_LEFTBRACE` | `SDL_SCANCODE_KP_LEFTBRACE` | |
1416
- | `sdl.keyboard.SCANCODE.KP_RIGHTBRACE` | `SDL_SCANCODE_KP_RIGHTBRACE` | |
1417
- | `sdl.keyboard.SCANCODE.KP_TAB` | `SDL_SCANCODE_KP_TAB` | |
1418
- | `sdl.keyboard.SCANCODE.KP_BACKSPACE` | `SDL_SCANCODE_KP_BACKSPACE` | |
1419
- | `sdl.keyboard.SCANCODE.KP_A` | `SDL_SCANCODE_KP_A` | |
1420
- | `sdl.keyboard.SCANCODE.KP_B` | `SDL_SCANCODE_KP_B` | |
1421
- | `sdl.keyboard.SCANCODE.KP_C` | `SDL_SCANCODE_KP_C` | |
1422
- | `sdl.keyboard.SCANCODE.KP_D` | `SDL_SCANCODE_KP_D` | |
1423
- | `sdl.keyboard.SCANCODE.KP_E` | `SDL_SCANCODE_KP_E` | |
1424
- | `sdl.keyboard.SCANCODE.KP_F` | `SDL_SCANCODE_KP_F` | |
1425
- | `sdl.keyboard.SCANCODE.KP_XOR` | `SDL_SCANCODE_KP_XOR` | |
1426
- | `sdl.keyboard.SCANCODE.KP_POWER` | `SDL_SCANCODE_KP_POWER` | |
1427
- | `sdl.keyboard.SCANCODE.KP_PERCENT` | `SDL_SCANCODE_KP_PERCENT` | |
1428
- | `sdl.keyboard.SCANCODE.KP_LESS` | `SDL_SCANCODE_KP_LESS` | |
1429
- | `sdl.keyboard.SCANCODE.KP_GREATER` | `SDL_SCANCODE_KP_GREATER` | |
1430
- | `sdl.keyboard.SCANCODE.KP_AMPERSAND` | `SDL_SCANCODE_KP_AMPERSAND` | |
1431
- | `sdl.keyboard.SCANCODE.KP_DBLAMPERSAND` | `SDL_SCANCODE_KP_DBLAMPERSAND` | |
1432
- | `sdl.keyboard.SCANCODE.KP_VERTICALBAR` | `SDL_SCANCODE_KP_VERTICALBAR` | |
1433
- | `sdl.keyboard.SCANCODE.KP_DBLVERTICALBAR` | `SDL_SCANCODE_KP_DBLVERTICALBAR` | |
1434
- | `sdl.keyboard.SCANCODE.KP_COLON` | `SDL_SCANCODE_KP_COLON` | |
1435
- | `sdl.keyboard.SCANCODE.KP_HASH` | `SDL_SCANCODE_KP_HASH` | |
1436
- | `sdl.keyboard.SCANCODE.KP_SPACE` | `SDL_SCANCODE_KP_SPACE` | |
1437
- | `sdl.keyboard.SCANCODE.KP_AT` | `SDL_SCANCODE_KP_AT` | |
1438
- | `sdl.keyboard.SCANCODE.KP_EXCLAM` | `SDL_SCANCODE_KP_EXCLAM` | |
1439
- | `sdl.keyboard.SCANCODE.KP_MEMSTORE` | `SDL_SCANCODE_KP_MEMSTORE` | |
1440
- | `sdl.keyboard.SCANCODE.KP_MEMRECALL` | `SDL_SCANCODE_KP_MEMRECALL` | |
1441
- | `sdl.keyboard.SCANCODE.KP_MEMCLEAR` | `SDL_SCANCODE_KP_MEMCLEAR` | |
1442
- | `sdl.keyboard.SCANCODE.KP_MEMADD` | `SDL_SCANCODE_KP_MEMADD` | |
1443
- | `sdl.keyboard.SCANCODE.KP_MEMSUBTRACT` | `SDL_SCANCODE_KP_MEMSUBTRACT` | |
1444
- | `sdl.keyboard.SCANCODE.KP_MEMMULTIPLY` | `SDL_SCANCODE_KP_MEMMULTIPLY` | |
1445
- | `sdl.keyboard.SCANCODE.KP_MEMDIVIDE` | `SDL_SCANCODE_KP_MEMDIVIDE` | |
1446
- | `sdl.keyboard.SCANCODE.KP_PLUSMINUS` | `SDL_SCANCODE_KP_PLUSMINUS` | |
1447
- | `sdl.keyboard.SCANCODE.KP_CLEAR` | `SDL_SCANCODE_KP_CLEAR` | |
1448
- | `sdl.keyboard.SCANCODE.KP_CLEARENTRY` | `SDL_SCANCODE_KP_CLEARENTRY` | |
1449
- | `sdl.keyboard.SCANCODE.KP_BINARY` | `SDL_SCANCODE_KP_BINARY` | |
1450
- | `sdl.keyboard.SCANCODE.KP_OCTAL` | `SDL_SCANCODE_KP_OCTAL` | |
1451
- | `sdl.keyboard.SCANCODE.KP_DECIMAL` | `SDL_SCANCODE_KP_DECIMAL` | |
1452
- | `sdl.keyboard.SCANCODE.KP_HEXADECIMAL` | `SDL_SCANCODE_KP_HEXADECIMAL` | |
1453
- | `sdl.keyboard.SCANCODE.LCTRL` | `SDL_SCANCODE_LCTRL` | |
1454
- | `sdl.keyboard.SCANCODE.LSHIFT` | `SDL_SCANCODE_LSHIFT` | |
1455
- | `sdl.keyboard.SCANCODE.LALT` | `SDL_SCANCODE_LALT` | alt, option |
1456
- | `sdl.keyboard.SCANCODE.LGUI` | `SDL_SCANCODE_LGUI` | windows, command (apple), meta |
1457
- | `sdl.keyboard.SCANCODE.RCTRL` | `SDL_SCANCODE_RCTRL` | |
1458
- | `sdl.keyboard.SCANCODE.RSHIFT` | `SDL_SCANCODE_RSHIFT` | |
1459
- | `sdl.keyboard.SCANCODE.RALT` | `SDL_SCANCODE_RALT` | alt gr, option |
1460
- | `sdl.keyboard.SCANCODE.RGUI` | `SDL_SCANCODE_RGUI` | windows, command (apple), meta |
1461
- | `sdl.keyboard.SCANCODE.MODE` | `SDL_SCANCODE_MODE` | |
1462
- | `sdl.keyboard.SCANCODE.AUDIONEXT` | `SDL_SCANCODE_AUDIONEXT` | |
1463
- | `sdl.keyboard.SCANCODE.AUDIOPREV` | `SDL_SCANCODE_AUDIOPREV` | |
1464
- | `sdl.keyboard.SCANCODE.AUDIOSTOP` | `SDL_SCANCODE_AUDIOSTOP` | |
1465
- | `sdl.keyboard.SCANCODE.AUDIOPLAY` | `SDL_SCANCODE_AUDIOPLAY` | |
1466
- | `sdl.keyboard.SCANCODE.AUDIOMUTE` | `SDL_SCANCODE_AUDIOMUTE` | |
1467
- | `sdl.keyboard.SCANCODE.MEDIASELECT` | `SDL_SCANCODE_MEDIASELECT` | |
1468
- | `sdl.keyboard.SCANCODE.WWW` | `SDL_SCANCODE_WWW` | |
1469
- | `sdl.keyboard.SCANCODE.MAIL` | `SDL_SCANCODE_MAIL` | |
1470
- | `sdl.keyboard.SCANCODE.CALCULATOR` | `SDL_SCANCODE_CALCULATOR` | |
1471
- | `sdl.keyboard.SCANCODE.COMPUTER` | `SDL_SCANCODE_COMPUTER` | |
1472
- | `sdl.keyboard.SCANCODE.AC_SEARCH` | `SDL_SCANCODE_AC_SEARCH` | |
1473
- | `sdl.keyboard.SCANCODE.AC_HOME` | `SDL_SCANCODE_AC_HOME` | |
1474
- | `sdl.keyboard.SCANCODE.AC_BACK` | `SDL_SCANCODE_AC_BACK` | |
1475
- | `sdl.keyboard.SCANCODE.AC_FORWARD` | `SDL_SCANCODE_AC_FORWARD` | |
1476
- | `sdl.keyboard.SCANCODE.AC_STOP` | `SDL_SCANCODE_AC_STOP` | |
1477
- | `sdl.keyboard.SCANCODE.AC_REFRESH` | `SDL_SCANCODE_AC_REFRESH` | |
1478
- | `sdl.keyboard.SCANCODE.AC_BOOKMARKS` | `SDL_SCANCODE_AC_BOOKMARKS` | |
1479
- | `sdl.keyboard.SCANCODE.BRIGHTNESSDOWN` | `SDL_SCANCODE_BRIGHTNESSDOWN` | |
1480
- | `sdl.keyboard.SCANCODE.BRIGHTNESSUP` | `SDL_SCANCODE_BRIGHTNESSUP` | |
1481
- | `sdl.keyboard.SCANCODE.DISPLAYSWITCH` | `SDL_SCANCODE_DISPLAYSWITCH` | display mirroring/dual display switch, video mode switch |
1482
- | `sdl.keyboard.SCANCODE.KBDILLUMTOGGLE` | `SDL_SCANCODE_KBDILLUMTOGGLE` | |
1483
- | `sdl.keyboard.SCANCODE.KBDILLUMDOWN` | `SDL_SCANCODE_KBDILLUMDOWN` | |
1484
- | `sdl.keyboard.SCANCODE.KBDILLUMUP` | `SDL_SCANCODE_KBDILLUMUP` | |
1485
- | `sdl.keyboard.SCANCODE.EJECT` | `SDL_SCANCODE_EJECT` | |
1486
- | `sdl.keyboard.SCANCODE.SLEEP` | `SDL_SCANCODE_SLEEP` | |
1487
- | `sdl.keyboard.SCANCODE.APP1` | `SDL_SCANCODE_APP1` | |
1488
- | `sdl.keyboard.SCANCODE.APP2` | `SDL_SCANCODE_APP2` | |
1489
- | `sdl.keyboard.SCANCODE.AUDIOREWIND` | `SDL_SCANCODE_AUDIOREWIND` | |
1490
- | `sdl.keyboard.SCANCODE.AUDIOFASTFORWARD` | `SDL_SCANCODE_AUDIOFASTFORWARD` | |
1491
-
1492
- </details>
1493
-
1494
- ### Event: 'keymapChange'
1495
-
1496
- Fired when the keymap changes due to a system event such as an input language or keyboard layout change.
1497
- After this event, the correspondance between physical and logical keys might have changed.
1498
- You should assume that any previous result you have gotten from [`getKey()`](#sdlkeyboardgetkeyscancode) or [`getScancode()`](#sdlkeyboardgetscancodekey) are not invalid.
1499
-
1500
- ### sdl.keyboard.getKey(scancode)
1501
-
1502
- - `scancode: `[`<Scancode>`](#enum-scancode)
1503
- - Returns: [`<Key>`](#virtual-keys)`|<null>`
1504
-
1505
- Maps a scancode to the corresponding key based on the current keyboard mapping.
1506
- Retuns `null` if the scancode does not currespond to a key in the current mapping.
1507
-
1508
- ### sdl.keyboard.getScancode(key)
1509
-
1510
- - `key: `[`<Key>`](#virtual-keys)
1511
- - Returns: [`<Scancode>`](#enum-scancode)`|<null>`
1512
-
1513
- Maps a key to the corresponding scancode based on the current keyboard mapping.
1514
- Retuns `null` if the key does not currespond to a scancode in the current mapping.
1515
- If multiple physical keys produce the same virtual key, then only the first one is returned.
1516
-
1517
- ### sdl.keyboard.getState()
1518
-
1519
- - Returns: `<boolean[]>` an array representing the state of each key.
1520
-
1521
- The returned array can be indexed with [`Scancode`](#enum-scancode) values.
1522
- Each value in the array is either `true` if the corresponding key is pressed, or `false` otherwise.
1523
-
1524
- ## sdl.mouse
1525
-
1526
- ### Enum: BUTTON
1527
-
1528
- Used to represent the buttons on a mouse.
1529
- A mouse can have many buttons, but the values for the three most common ones are represented in this enum.
1530
-
1531
- | Value | Corresponding `SDL_BUTTON_*` |
1532
- | --- | --- |
1533
- | `sdl.mouse.BUTTON.LEFT` | `SDL_BUTTON_LEFT` |
1534
- | `sdl.mouse.BUTTON.MIDDLE` | `SDL_BUTTON_MIDDLE` |
1535
- | `sdl.mouse.BUTTON.RIGHT` | `SDL_BUTTON_RIGHT` |
1536
-
1537
- ### sdl.mouse.getButton(button)
1538
-
1539
- - `button: <number>` The index of the button.
1540
- - Returns: `<boolean>` Is `true` if the button is pressed.
1541
-
1542
- Queries the state of a single mouse button.
1543
-
1544
- ### sdl.mouse.position
1545
-
1546
- - `<object>`
1547
- - `x: <number>` The x position of the mouse, relative to the screen.
1548
- - `y: <number>` The y position of the mouse, relative to the screen.
1549
-
1550
- The position of the mouse on the screen.
1551
-
1552
- ### sdl.mouse.setPosition(x, y)
1553
-
1554
- - `x: <number>` The new x position of the mouse, relative to the screen.
1555
- - `y: <number>` The new y position of the mouse, relative to the screen.
1556
-
1557
- Moves the mouse to the specified position.
1558
-
1559
- ### sdl.mouse.setCursor(cursor)
1560
-
1561
- - `cursor: <MouseCursor>` The icon to use for the cursor.
1562
-
1563
- Changes the icon that is displayed for the mouse cursor.
1564
-
1565
- Possible values for `cursor` are:
1566
-
1567
- | Value | Corresponding `SDL_SystemCursor` | Description |
1568
- | --- | --- | --- |
1569
- | `'arrow'` | `SDL_SYSTEM_CURSOR_ARROW` | arrow |
1570
- | `'ibeam'` | `SDL_SYSTEM_CURSOR_IBEAM` | i-beam |
1571
- | `'wait'` | `SDL_SYSTEM_CURSOR_WAIT` | wait |
1572
- | `'crosshair'` | `SDL_SYSTEM_CURSOR_CROSSHAIR` | crosshair |
1573
- | `'waitarrow'` | `SDL_SYSTEM_CURSOR_WAITARROW` | small wait cursor (or wait if not available) |
1574
- | `'sizenwse'` | `SDL_SYSTEM_CURSOR_SIZENWSE` | double arrow pointing northwest and southeast |
1575
- | `'sizenesw'` | `SDL_SYSTEM_CURSOR_SIZENESW` | double arrow pointing northeast and southwest |
1576
- | `'sizewe'` | `SDL_SYSTEM_CURSOR_SIZEWE` | double arrow pointing west and east |
1577
- | `'sizens'` | `SDL_SYSTEM_CURSOR_SIZENS` | double arrow pointing north and south |
1578
- | `'sizeall'` | `SDL_SYSTEM_CURSOR_SIZEALL` | four pointed arrow pointing north, south, east, and west |
1579
- | `'no'` | `SDL_SYSTEM_CURSOR_NO` | slashed circle or crossbones |
1580
- | `'hand'` | `SDL_SYSTEM_CURSOR_HAND` | hand |
1581
-
1582
- ### sdl.mouse.resetCursor()
1583
-
1584
- Switched back to the default cursor.
1585
-
1586
- ### sdl.mouse.setCursorImage(width, height, stride, format, buffer, x, y)
1587
-
1588
- - `width, height, stride, format, buffer: `[`<Image>`](#image-data) The image to use as a cursor.
1589
- - `x: <number>` The x position of the cursor image's hotspot.
1590
- - `y: <number>` The y position of the cursor image's hotspot.
1591
-
1592
- Sets a image to be the mouse cursor.
1593
- The hotspot represents the pixel that is considered to be under the mouse.
1594
-
1595
- ### sdl.mouse.showCursor([show])
1596
-
1597
- - `show: <boolean>` If `true` then the mouse cursor is made visible. Default: `true`
1598
-
1599
- Changes the visibility of the mouse cursor.
1600
-
1601
- ### sdl.mouse.hideCursor()
1602
-
1603
- Equivalent to [`sdl.mouse.showCursor(false)`](#sdlmouseshowcursorshow).
1604
-
1605
- ### sdl.mouse.redrawCursor()
1606
-
1607
- Forces a cursor redraw.
1608
-
1609
- ### sdl.mouse.capture([capture])
1610
-
1611
- - `capture: <boolean>` If `true` the mouse is to be captured by the current window. Default: `true`
1612
-
1613
- When the mouse has been captured you will continue receiving mouse events even if the mouse is not over a window.
1614
-
1615
- ### sdl.mouse.uncapture()
1616
-
1617
- Equivalent to [`sdl.mouse.capture(false)`](#sdlmousecapturecapture).
1618
-
1619
- ## sdl.touch
1620
-
1621
- ### sdl.touch.devices
1622
-
1623
- - `<object>[]`
1624
- - `id: <number>` The unique id for the device.
1625
- - `name: <string>|<null>` The name of the device, or `null` if it can't be determined.
1626
- - `type: <TouchDeviceType>|<null>` The type of the device, or `null` if it can't be determined.
1627
-
1628
- A list of all the detected touch devices.
1629
- On some platforms SDL only sees the touch device after it has actually been used.
1630
- Therefore the returned list might be empty, although devices are available.
1631
- After using all devices at least once the number will be correct.
1632
-
1633
- Possible values for `type` are `null` if it is unknown, or one of:
1634
-
1635
- | Value | Corresponding `SDL_TouchDeviceType` |
1636
- | --- | --- |
1637
- | `'direct'` | `SDL_TOUCH_DEVICE_DIRECT` |
1638
- | `'indirectAbsolute'` | `SDL_TOUCH_DEVICE_INDIRECT_ABSOLUTE` |
1639
- | `'indirectRelative'` | `SDL_TOUCH_DEVICE_INDIRECT_RELATIVE` |
1640
-
1641
- // TODO Sample output
1642
-
1643
- ## sdl.joystick
1644
-
1645
- ### Hat positions
1646
-
1647
- String values used to represent the positions of a joystick hat
1648
-
1649
- | Value | Corresponding `SDL_HAT_*` |
1650
- | --- | --- |
1651
- | `'centered'` | `SDL_HAT_CENTERED` |
1652
- | `'up'` | `SDL_HAT_UP` |
1653
- | `'right'` | `SDL_HAT_RIGHT` |
1654
- | `'down'` | `SDL_HAT_DOWN` |
1655
- | `'left'` | `SDL_HAT_LEFT` |
1656
- | `'rightup'` | `SDL_HAT_RIGHTUP` |
1657
- | `'rightdown'` | `SDL_HAT_RIGHTDOWN` |
1658
- | `'leftup'` | `SDL_HAT_LEFTUP` |
1659
- | `'leftdown'` | `SDL_HAT_LEFTDOWN` |
1660
-
1661
- ### Power levels
1662
-
1663
- String values used to represent the power level of a joystick or controller
1664
-
1665
- | Value | Corresponding `SDL_JoystickPowerLevel` |
1666
- | --- | --- |
1667
- | `'empty'` | `SDL_JOYSTICK_POWER_EMPTY` |
1668
- | `'low'` | `SDL_JOYSTICK_POWER_LOW` |
1669
- | `'medium'` | `SDL_JOYSTICK_POWER_MEDIUM` |
1670
- | `'full'` | `SDL_JOYSTICK_POWER_FULL` |
1671
- | `'wired'` | `SDL_JOYSTICK_POWER_WIRED` |
1672
- | `'max'` | `SDL_JOYSTICK_POWER_MAX` |
1673
-
1674
- <a id="joystick-event-deviceadd"></a>
1675
-
1676
- ### Event: 'deviceAdd'
1677
-
1678
- - `device: <object>`: An object from [`sdl.joystick.devices`](#sdljoystickdevices) indicating the device that caused the event.
1679
-
1680
- Fired when a new joystick device becomes available.
1681
- Check [`sdl.joystick.devices`](#sdljoystickdevices) to get the new list of joystick devices.
1682
-
1683
- <a id="joystick-event-deviceremove"></a>
1684
-
1685
- ### Event: 'deviceRemove'
1686
-
1687
- - `device: <object>`: An object from [`sdl.joystick.devices`](#sdljoystickdevices) indicating the device that caused the event.
1688
-
1689
- Fired when an existing joystick device is removed.
1690
- Check [`sdl.joystick.devices`](#sdljoystickdevices) to get the new list of joystick devices.
1691
- When this event is emitted, all instances that were opened from the removed device are closed automatically.
1692
-
1693
- ### sdl.joystick.devices
1694
-
1695
- - `<object>[]`
1696
- - `id: <number>` The unique id for the device.
1697
- - `name: <string>|<null>` The name of the device.
1698
- - `path: <string>|<null>` The implementation dependent path of the device, or `null` if it can't be determined.
1699
- - `type: <JoystickType>|<null>` The type of the device, or `null` if it can't be determined.
1700
- - `guid: <string>|<null>` The GUID of the device, or `null` if it can't be determined.
1701
- - `vendor: <number>|<null>` The USB vendor ID of the device, or `null` if it can't be determined.
1702
- - `product: <number>|<null>` The USB product ID of the device, or `null` if it can't be determined.
1703
- - `version: <number>|<null>` The USB product version of the device, or `null` if it can't be determined.
1704
- - `player: <number>|<null>` The player index for the device, or `null` if it can't be determined.
1705
-
1706
- A list of all the detected joystick devices.
1707
-
1708
- Possible values for `type` are `null` if it is unknown, or one of:
1709
-
1710
- | Value | Corresponding `SDL_JoystickType` |
1711
- | --- | --- |
1712
- | `'gamecontroller'` | `SDL_JOYSTICK_TYPE_GAMECONTROLLER` |
1713
- | `'wheel'` | `SDL_JOYSTICK_TYPE_WHEEL` |
1714
- | `'arcadestick'` | `SDL_JOYSTICK_TYPE_ARCADE_STICK` |
1715
- | `'flightstick'` | `SDL_JOYSTICK_TYPE_FLIGHT_STICK` |
1716
- | `'dancepad'` | `SDL_JOYSTICK_TYPE_DANCE_PAD` |
1717
- | `'guitar'` | `SDL_JOYSTICK_TYPE_GUITAR` |
1718
- | `'drumkit'` | `SDL_JOYSTICK_TYPE_DRUM_KIT` |
1719
- | `'arcadepad'` | `SDL_JOYSTICK_TYPE_ARCADE_PAD` |
1720
- | `'throttle'` | `SDL_JOYSTICK_TYPE_THROTTLE` |
1721
-
1722
- Sample output:
1723
-
1724
- ```js
1725
- [
1726
- {
1727
- id: 0,
1728
- name: 'DragonRise Inc. Generic USB Joystick',
1729
- path: '/dev/input/event21',
1730
- guid: '03000000790000000600000010010000',
1731
- type: 'gamecontroller',
1732
- vendor: 121,
1733
- product: 6,
1734
- version: 272,
1735
- player: 0,
1736
- },
1737
- ]
1738
- ```
1739
-
1740
- ### sdl.joystick.openDevice(device)
1741
-
1742
- - `device: <object>` An object from [`sdl.joystick.devices`](#sdljoystickdevices) that is to be opened.
1743
- - Returns: [`<joystickInstance>`](#class-joystickinstance) an object representing the opened joystick device instance.
1744
-
1745
- Initializes a joystick device and returns a corresponding instance.
1746
-
1747
- ## class joystickInstance
1748
-
1749
- The `JoystickInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
1750
- Instead, objects returned by [`sdl.joystick.openDevice()`](#sdljoystickopendevicedevice) are of type `JoystickInstance`.
1751
-
1752
- <a id="joystick-instance-event-axismotion"></a>
1753
-
1754
- ### Event: 'axisMotion'
1755
-
1756
- - `axis: <number>` The index of the axis that moved.
1757
- - `value: <number>` The new axis position.
1758
-
1759
- Fired when one of the joystick's axes moves.
1760
-
1761
- ### Event: 'ballMotion'
1762
-
1763
- - `ball: <number>` The index of the ball that moved.
1764
- - `x: <number>` The new x-position of the ball.
1765
- - `y: <number>` The new y-position of the ball.
1766
-
1767
- Fired when one of the joystick's balls moves.
1768
-
1769
- <a id="joystick-instance-event-buttondown"></a>
1770
-
1771
- ### Event: 'buttonDown'
1772
-
1773
- - `button: <number>` The index of the button that was pressed.
1774
-
1775
- Fired when one of the joystick's buttons is pressed.
1776
-
1777
- <a id="joystick-instance-event-buttonup"></a>
1778
-
1779
- ### Event: 'buttonUp'
1780
-
1781
- - `button: <number>` The index of the button that was released.
1782
-
1783
- Fired when one of the joystick's buttons is released.
1784
-
1785
- ### Event: 'hatMotion'
1786
-
1787
- - `hat: <number>` The index of the hat that was moved.
1788
- - `value: `[`<HatPosition>`](#hat-positions) The new hat position.
1789
-
1790
- Fired when one of the joystick's hats is moved.
1791
-
1792
- <a id="joystick-instance-event-power-update"></a>
1793
-
1794
- ### Event: 'powerUpdate'
1795
-
1796
- - `power: `[`<PowerLevel>`](#power-levels)`|<null>` The new power level.
1797
-
1798
- Fired when the joystick's [power level](#controllerinstancepower) changes.
1799
-
1800
- <a id="joystick-instance-event-close"></a>
1801
-
1802
- ### Event: 'close'
1803
-
1804
- Fired when the instance is about to close.
1805
- Handle cleanup here.
1806
-
1807
- ### joystickInstance.device
1808
-
1809
- - `<object>`
1810
-
1811
- The [device](#sdljoystickdevices) from which the instance was opened.
1812
-
1813
- ### joystickInstance.firmwareVersion
1814
-
1815
- - `<number>|<null>`
1816
-
1817
- The joystick's firmware version, or `null` if it is not available.
1818
-
1819
- ### joystickInstance.serialNumber
1820
-
1821
- - `<string>|<null>`
1822
-
1823
- The joystick's serial number, or `null` if it is not available.
1824
-
1825
- ### joystickInstance.axes
1826
-
1827
- - `<number>[]`
1828
-
1829
- An array of values, each corresponding to the position of one of the joystick's axes.
1830
- The values are normalized in the range from `-1` to `+1`.
1831
- It may be necessary to impose certain tolerances on these values to account for jitter.
1832
-
1833
- ### joystickInstance.balls
1834
-
1835
- - `<object>[]`
1836
- - `x: <number>` The horizontal position of the joystick's ball.
1837
- - `y: <number>` The vertical position of the joystick's ball.
1838
-
1839
- An array of values, each corresponding to the position of one of the joystick's balls.
1840
-
1841
- ### joystickInstance.buttons
1842
-
1843
- - `<boolean>[]`
1844
-
1845
- An array of values, each corresponding to the state of one of the joystick's buttons.
1846
- Each value in the object isarray is either `true` if the corresponding button is pressed, or `false` otherwise.
1847
-
1848
- ### joystickInstance.hats
1849
-
1850
- - [`<HatPosition>`](#hat-positions)`[]`
1851
-
1852
- An array of values, each corresponding to the position of one of the joystick's hats.
1853
-
1854
- ### joystickInstance.power
1855
-
1856
- - [`<PowerLevel>`](#power-levels)`|<null>`
1857
-
1858
- The current power level of the joystick device, or `null` if it is unknown.
1859
-
1860
- ### joystickInstance.setPlayer(index)
1861
-
1862
- - `index: <number>` The player index to assign to the joystick.
1863
-
1864
- Sets the player index of the joystick.
1865
-
1866
- ### joystickInstance.resetPlayer()
1867
-
1868
- Clears player assignment and player led.
1869
-
1870
- ### joystickInstance.hasLed
1871
-
1872
- - `<boolean>`
1873
-
1874
- Is `true` if the joystick has a LED light whose color can be controlled.
1875
-
1876
- ### joystickInstance.setLed(red, green, blue)
1877
-
1878
- - `red: <number>` The red component of the led color, from `0` to `1`.
1879
- - `green: <number>` The green component of the led color, from `0` to `1`.
1880
- - `blue: <number>` The blue component of the led color, from `0` to `1`.
1881
-
1882
- Sets the color of the LED light on the joystick.
1883
-
1884
- ### joystickInstance.hasRumble
1885
-
1886
- - `<boolean>`
1887
-
1888
- Is `true` if the joystick has rumble motors.
1889
-
1890
- ### joystickInstance.rumble([low[, high[, duration]]])
1891
-
1892
- - `low: <number>` The intensity of the low frequency rumble motor, from `0` to `1`. Default: `1`
1893
- - `high: <number>` The intensity of the high frequency rumble motor, from `0` to `1`. Default: `1`
1894
- - `duration: <number>` The duration of the rumble, in ms. Default: `1e3`
1895
-
1896
- Makes the joystick rumble for a set `duration`.
1897
- Calling this function again before `duration` has ran out, overrides the previous call.
1898
-
1899
- ### joystickInstance.stopRumble()
1900
-
1901
- Stops the joystick rumbling.
1902
- Equivalent to [`joystickInstance.rumble(0, 0)`](#joystickinstancerumblelow-high-duration).
1903
-
1904
- ### joystickInstance.hasRumbleTriggers
1905
-
1906
- - `<boolean>`
1907
-
1908
- Is `true` if the joystick has rumble motors on the triggers.
1909
-
1910
- ### joystickInstance.rumbleTriggers([left[, right[, duration]]])
1911
-
1912
- - `left: <number>` The intensity of the left trigger rumble motor, from `0` to `1`. Default: `1`
1913
- - `right: <number>` The intensity of the right trigger rumble motor, from `0` to `1`. Default: `1`
1914
- - `duration: <number>` The duration of the rumble, in ms. Default: `1e3`
1915
-
1916
- Makes the joystick triggers rumble for a set `duration`.
1917
- Calling this function again before `duration` has ran out, overrides the previous call.
1918
-
1919
- ### joystickInstance.stopRumbleTriggers()
1920
-
1921
- Stops the joystick trigger rumbling.
1922
- Equivalent to [`joystickInstance.rumbleTriggers(0, 0)`](#joystickinstancerumbletriggersleft-right-duration).
1923
-
1924
- ### joystickInstance.closed
1925
-
1926
- - `<boolean>`
1927
-
1928
- Is `true` if the instance is closed.
1929
- A closed instance object must not be used any further.
1930
-
1931
- ### joystickInstance.close()
1932
-
1933
- Closes the instance.
1934
-
1935
- ## sdl.controller
1936
-
1937
- 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").
1938
- 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 button of the 4 buttons on the right.
1939
- This makes it easy to provide consistent input bindings, like "press B to jump, move around with the left analog stick".
1940
- With a pure joystick instance it's impossible to know which axis or button corresponds to which physical axis/button on the device.
1941
-
1942
- 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).
1943
- For a joystick device to also be available as a controller device it needs a "mapping".
1944
- A mapping is a string that consists of the device's GUID, its name, and a series of pairings between one joystick axis/button and the corresponding controller axis/button name.
1945
- See the sample output [`here`](#sdlcontrollerdevices) for an example.
1946
- SDL has pretty good default controller mappings, but if you need more, there's a community sourced database available on [gabomdq/SDL_GameControllerDB](https://github.com/gabomdq/SDL_GameControllerDB).
1947
- Add them via:
1948
-
1949
- ```js
1950
- const url = 'https://raw.githubusercontent.com/gabomdq/SDL_GameControllerDB/master/gamecontrollerdb.txt'
1951
- const result = await fetch(url)
1952
- const text = await result.text()
1953
- const mappings = text.split('\n').filter((line) => line && !line.startsWith('#'))
1954
- sdl.controller.addMappings(mappings)
1955
- ```
1956
-
1957
- <a id="controller-event-deviceadd"></a>
1958
-
1959
- ### Event: 'deviceAdd'
1960
-
1961
- - `device: <object>`: An object from [`sdl.controller.devices`](#sdlcontrollerdevices) indicating the device that caused the event.
1962
-
1963
- Fired when a new controller device becomes available.
1964
- Check [`sdl.controller.devices`](#sdlcontrollerdevices) to get the new list of controller devices.
1965
-
1966
- <a id="controller-event-deviceremove"></a>
1967
-
1968
- ### Event: 'deviceRemove'
1969
-
1970
- - `device: <object>`: An object from [`sdl.controller.devices`](#sdlcontrollerdevices) indicating the device that caused the event.
1971
-
1972
- Fired when an existing controller device is removed.
1973
- Check [`sdl.controller.devices`](#sdlcontrollerdevices) to get the new list of controller devices.
1974
- When this event is emitted, all instances that were opened from the removed device are closed automatically.
1975
-
1976
- ### sdl.controller.addMappings(mappings)
1977
-
1978
- - `mappings: <string>[]` An array of mappings to register.
1979
-
1980
- Registers new mappings for controllers.
1981
- This may cause already opened controller instances to be [remapped](#event-remap).
1982
-
1983
- ### sdl.controller.devices
1984
-
1985
- - `<object>[]`
1986
- - `id: <number>` The unique id for the device.
1987
- - `name: <string>|<null>` The name of the device.
1988
- - `path: <string>|<null>` The implementation dependent path of the device, or `null` if it can't be determined.
1989
- - `type: <string>|<null>` The type of the device, or `null` if it can't be determined.
1990
- - `guid: <string>|<null>` The GUID of the device, or `null` if it can't be determined.
1991
- - `vendor: <number>|<null>` The USB vendor ID of the device, or `null` if it can't be determined.
1992
- - `product: <number>|<null>` The USB product ID of the device, or `null` if it can't be determined.
1993
- - `version: <number>|<null>` The USB product version of the device, or `null` if it can't be determined.
1994
- - `player: <number>|<null>` The player index for the device, or `null` if it can't be determined.
1995
- - `mapping: <string>|<null>` The axis and button mapping for the device, or `null` if it can't be determined.
1996
-
1997
- A list of all the detected controller devices.
1998
-
1999
- Possible values for `type` are `null` if it is unknown, or one of:
2000
-
2001
- | Value | Corresponding `SDL_GameControllerType` |
2002
- | --- | --- |
2003
- | `'xbox360'` | SDL_CONTROLLER_TYPE_XBOX360 |
2004
- | `'xboxOne'` | SDL_CONTROLLER_TYPE_XBOXONE |
2005
- | `'ps3'` | SDL_CONTROLLER_TYPE_PS3 |
2006
- | `'ps4'` | SDL_CONTROLLER_TYPE_PS4 |
2007
- | `'nintendoSwitchPro'` | SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_PRO |
2008
- | `'virtual'` | SDL_CONTROLLER_TYPE_VIRTUAL |
2009
- | `'ps5'` | SDL_CONTROLLER_TYPE_PS5 |
2010
- | `'amazonLuna'` | SDL_CONTROLLER_TYPE_AMAZON_LUNA |
2011
- | `'googleStadia'` | SDL_CONTROLLER_TYPE_GOOGLE_STADIA |
2012
- | `'nvidiaShield'` | SDL_CONTROLLER_TYPE_NVIDIA_SHIELD |
2013
- | `'nintendoSwitchJoyconLeft'` | SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_LEFT |
2014
- | `'nintendoSwitchJoyconRight'` | SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT |
2015
- | `'nintendoSwitchJoyconPair'` | SDL_CONTROLLER_TYPE_NINTENDO_SWITCH_JOYCON_PAIR |
2016
-
2017
- Sample output:
2018
-
2019
- ```js
2020
- [
2021
- {
2022
- id: 0,
2023
- name: 'DragonRise Inc. Generic USB Joystick',
2024
- path: '/dev/input/event21',
2025
- guid: '03000000790000000600000010010000',
2026
- type: null,
2027
- vendor: 121,
2028
- product: 6,
2029
- version: 272,
2030
- player: 0,
2031
- 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,',
2032
- },
2033
- ]
2034
- ```
2035
-
2036
- ### sdl.controller.openDevice(device)
2037
-
2038
- - `device: <object>` An object from [`sdl.controller.devices`](#sdlcontrollerdevices) that is to be opened.
2039
- - Returns: [`<ControllerInstance>`](#class-controllerinstance) an object representing the opened controller device instance.
2040
-
2041
- Initializes an controller device and returns a corresponding instance.
2042
-
2043
- ## class ControllerInstance
2044
-
2045
- The `ControllerInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
2046
- Instead, objects returned by [`sdl.controller.openDevice()`](#sdlcontrolleropendevicedevice) are of type `ControllerInstance`.
2047
-
2048
- <a id="controller-instance-event-axismotion"></a>
2049
-
2050
- ### Event: 'axisMotion'
2051
-
2052
- - `axis:`[`<Axis>`](#controllerinstanceaxes) The axis that moved.
2053
- - `value: <number>` The new axis position.
2054
-
2055
- Fired when one of the controller's axes moves.
2056
-
2057
- <a id="controller-instance-event-buttondown"></a>
2058
-
2059
- ### Event: 'buttonDown'
2060
-
2061
- - `button:`[`<Button>`](#controllerinstancebuttons) The button that was pressed.
2062
-
2063
- Fired when one of the controller's buttons is pressed.
2064
-
2065
- <a id="controller-instance-event-buttonup"></a>
2066
-
2067
- ### Event: 'buttonUp'
2068
-
2069
- - `button: <number>` The index of the button that was released.
2070
-
2071
- Fired when one of the controller's buttons is released.
2072
-
2073
- <a id="controller-instance-event-power-update"></a>
2074
-
2075
- ### Event: 'powerUpdate'
2076
-
2077
- - `power: `[`<PowerLevel>`](#power-levels)`|<null>` The new power level.
2078
-
2079
- Fired when the controller's [power level](#controllerinstancepowerlevel) changes.
2080
-
2081
- ### Event: 'steamHandleUpdate'
2082
-
2083
- - `steamHandle: <Buffer>|<null>` The new steam handle.
2084
-
2085
- Fired when the controller's [`steamHandle`](#controllerinstancesteamhandle) changes.
2086
-
2087
- ### Event: 'remap'
2088
-
2089
- Fired when a new mapping for the controller is applied (usually via [`sdl.controller.addMappings()`](#sdlcontrolleraddmappingsmappings)).
2090
- This may cause all of the controller's axes and buttons to aquire new values.
2091
-
2092
- <a id="controller-instance-event-close"></a>
2093
-
2094
- ### Event: 'close'
2095
-
2096
- Fired when the instance is about to close.
2097
- Handle cleanup here.
2098
-
2099
- ### controllerInstance.device
2100
-
2101
- - `<object>`
2102
-
2103
- The [device](#sdlcontrollerdevices) from which the instance was opened.
2104
-
2105
- ### controllerInstance.firmwareVersion
2106
-
2107
- - `<number>`
2108
-
2109
- The controller's firmware version.
2110
-
2111
- ### controllerInstance.serialNumber
2112
-
2113
- - `<string>|<null>`
2114
-
2115
- The controller's serial number, or `null` if it is not available.
2116
-
2117
- ### controllerInstance.steamHandle
2118
-
2119
- - `<Buffer>|<null>`
2120
-
2121
- The controller's steam handle, or `null` if it is not available.
2122
- The `Buffer` contains an `InputHandle_t` for the controller that can be used with the [Steam Input API](https://partner.steamgames.com/doc/api/ISteamInput)
2123
-
2124
- ### controllerInstance.axes
2125
-
2126
- - `<object>`
2127
- - `leftStickX: <number>` Left stick horizontal position
2128
- - `leftStickY: <number>` Left stick vertical position
2129
- - `rightStickX: <number>` Right stick horizontal position
2130
- - `rightStickY: <number>` Right stick vertical position
2131
- - `leftTrigger: <number>` Left trigger position
2132
- - `rightTrigger: <number>` Right trigger position
2133
-
2134
- An object mapping each axis of the controller's axes to its position.
2135
- The values are normalized in the range from `-1` to `+1`.
2136
- It may be necessary to impose certain tolerances on these values to account for jitter.
2137
-
2138
- ### controllerInstance.buttons
2139
-
2140
- - `<object>`
2141
- - `dpadLeft: <boolean>` D-Pad left pressed
2142
- - `dpadRight: <boolean>` D-Pad right pressed
2143
- - `dpadUp: <boolean>` D-Pad up pressed
2144
- - `dpadDown: <boolean>` D-Pad down pressed
2145
- - `a: <boolean>` A button pressed
2146
- - `b: <boolean>` B button pressed
2147
- - `x: <boolean>` X button pressed
2148
- - `y: <boolean>` Y button pressed
2149
- - `guide: <boolean>` Middle button pressed
2150
- - `back: <boolean>` Back button pressed
2151
- - `start: <boolean>` Start button pressed
2152
- - `leftStick: <boolean>` Left stick pressed
2153
- - `rightStick: <boolean>` Right stick pressed
2154
- - `leftShoulder: <boolean>` Left shoulder button pressed
2155
- - `rightShoulder: <boolean>` Right shoulder button pressed
2156
- - `paddle1: <boolean>` Paddle 1 pressed
2157
- - `paddle2: <boolean>` Paddle 2 pressed
2158
- - `paddle3: <boolean>` Paddle 3 pressed
2159
- - `paddle4: <boolean>` Paddle 4 pressed
2160
-
2161
- An object mapping each of the controller's buttons to a boolean value.
2162
- Each value in the object is either `true` if the corresponding button is pressed, or `false` otherwise.
2163
-
2164
- ### controllerInstance.power
2165
-
2166
- - [`<PowerLevel>`](#power-levels)`|<null>`
2167
-
2168
- The current power level of the joystick device, or `null` if it is unknown.
2169
-
2170
- ### controllerInstance.setPlayer(index)
2171
-
2172
- - `index: <number>` The player index to assign to the controller.
2173
-
2174
- Sets the player index of the controller.
2175
-
2176
- ### controllerInstance.resetPlayer()
2177
-
2178
- Clears player assignment and player led.
2179
-
2180
- ### controllerInstance.hasLed
2181
-
2182
- - `<boolean>`
2183
-
2184
- Is `true` if the controller has a LED light whose color can be controlled.
2185
-
2186
- ### controllerInstance.setLed(red, green, blue)
2187
-
2188
- - `red: <number>` The red component of the led color, from `0` to `1`.
2189
- - `green: <number>` The green component of the led color, from `0` to `1`.
2190
- - `blue: <number>` The blue component of the led color, from `0` to `1`.
2191
-
2192
- Sets the color of the LED light on the controller.
2193
-
2194
- ### controllerInstance.hasRumble
2195
-
2196
- - `<boolean>`
2197
-
2198
- Is `true` if the controller has rumble motors.
2199
-
2200
- ### controllerInstance.rumble([low[, high[, duration]]])
2201
-
2202
- - `low: <number>` The intensity of the low frequency rumble motor, from `0` to `1`. Default: `1`
2203
- - `high: <number>` The intensity of the high frequency rumble motor, from `0` to `1`. Default: `1`
2204
- - `duration: <number>` The duration of the rumble, in ms. Default: `1e3`
2205
-
2206
- Makes the controller rumble for a set `duration`.
2207
- Calling this function again before `duration` has ran out, overrides the previous call.
2208
-
2209
- ### controllerInstance.stopRumble()
2210
-
2211
- Stops the controller rumbling.
2212
- Equivalent to [`controllerInstance.rumble(0, 0)`](#controllerinstancerumblelow-high-duration).
2213
-
2214
- ### controllerInstance.hasRumbleTriggers
2215
-
2216
- - `<boolean>`
2217
-
2218
- Is `true` if the controller has rumble motors on the triggers.
2219
-
2220
- ### controllerInstance.rumbleTriggers([left[, right[, duration]]])
2221
-
2222
- - `left: <number>` The intensity of the left trigger rumble motor, from `0` to `1`. Default: `1`
2223
- - `right: <number>` The intensity of the right trigger rumble motor, from `0` to `1`. Default: `1`
2224
- - `duration: <number>` The duration of the rumble, in ms. Default: `1e3`
2225
-
2226
- Makes the controller triggers rumble for a set `duration`.
2227
- Calling this function again before `duration` has ran out, overrides the previous call.
2228
-
2229
- ### controllerInstance.stopRumbleTriggers()
2230
-
2231
- Stops the controller trigger rumbling.
2232
- Equivalent to [`controllerInstance.rumbleTriggers(0, 0)`](#controllerinstancerumbletriggersleft-right-duration).
2233
-
2234
- ### controllerInstance.closed
2235
-
2236
- - `<boolean>`
2237
-
2238
- Is `true` if the instance is closed.
2239
- A closed instance object must not be used any further.
2240
-
2241
- ### controllerInstance.close()
2242
-
2243
- Closes the instance.
2244
-
2245
- ## sdl.sensor
2246
-
2247
- ### sdl.sensor.STANDARD_GRAVITY
2248
-
2249
- - `<number>`
2250
-
2251
- Accelerometers are affected by the force of gravity:
2252
- even if the device is completely at rest, it will still indicata an acceleration with a magnitude of [`sdl.sensor.STANDARD_GRAVITY`](#sdlsensorstandard_gravity) away from the center of the earth.
2253
- Use the `sdl.sensor.STANDARD_GRAVITY` constant to correct for gravitational acceleration if your application requires it.
2254
-
2255
- ### sdl.sensor.devices
2256
-
2257
- - `<object>[]`
2258
- - `id: <number>` The unique id of the device.
2259
- - `name: <string>` The name of the device.
2260
- - `type: <string>|<null>` Either `'accelerometer'` or `'gyroscope'`. Is `null` if it can't be determined.
2261
- - `side: <string>|<null>` Either `'left'` or `'right'`. Is `null` if the sensor does not have a side, or the value can't be determined.
2262
-
2263
- A list of all the detected sensor devices.
2264
-
2265
- Some sensors have a `side`, sucha as those on the Joy-Con controller.
2266
- For most other sensors `side` is `null`.
2267
-
2268
- Sample output:
2269
-
2270
- // TODO
2271
-
2272
- ### sdl.sensor.openDevice(device)
2273
-
2274
- - `device: <object>` An object from [`sdl.sensor.devices`](#sdlsensordevices) that is to be opened.
2275
- - Returns: [`<SensorInstance>`](#class-sensorinstance) an object representing the opened sensor device instance.
2276
-
2277
- Initializes a sensor device and returns a corresponding instance.
2278
-
2279
- ## class SensorInstance
2280
-
2281
- The `SensorInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
2282
- Instead, objects returned by [`sdl.sensor.openDevice()`](#sdlsensoropendevicedevice) are of type `SensorInstance`.
2283
-
2284
- <a id="sensor-instance-event-update"></a>
2285
-
2286
- ### Event: 'update'
2287
-
2288
- Fired when the sensor's data changes.
2289
- Get the new data by accessing [`sensorInstance.data`](#sensorinstancedata)
2290
-
2291
- <a id="sensor-instance-event-close"></a>
2292
-
2293
- ### Event: 'close'
2294
-
2295
- Fired when the instance is about to close.
2296
- Handle cleanup here.
2297
-
2298
- ### sensorInstance.device
2299
-
2300
- - `<object>`
2301
-
2302
- The [device](#sdlsensordevices) from which the `sensorInstance` was opened.
2303
-
2304
- ### sensorInstance.data
2305
-
2306
- - `<object>`
2307
- - `timestamp: <number>|<null>` The time the latest measurement was taken __in microseconds__, or `null` if it can't be determined.
2308
- - `x: <number>` X axis value.
2309
- - `y: <number>` Y axis value.
2310
- - `z: <number>` Z axis value.
2311
-
2312
- An object reporting the latest measurement from the sensor.
2313
-
2314
- For accelerometers, the `x`, `y`, and `z` values correspond to the current acceleration in meters per second squared.
2315
- Keep in mind the accelerometers are affected by the force of gravity:
2316
- even if the device is completely at rest, it will still indicata an acceleration with a magnitude of [`sdl.sensor.STANDARD_GRAVITY`](#sdlsensorstandard_gravity) away from the center of the earth.
2317
-
2318
- For gyroscopes, the `x`, `y`, and `z` values correspond to the current rate of rotation in radians per second.
2319
- The rotation is positive in the counter-clockwise direction, meaning that an observer looking from a positive location on one of the axes would see positive rotation on that axis when it appeared to be rotating counter-clockwise.
2320
-
2321
- For phones held in portrait mode and game controllers held in front of you, the axes are defined as follows:
2322
-
2323
- - -X ... +X : left ... right
2324
- - -Y ... +Y : bottom ... top
2325
- - -Z ... +Z : farther ... closer
2326
-
2327
- ### sensorInstance.closed
2328
-
2329
- - `<boolean>`
2330
-
2331
- Is `true` if the instance is closed.
2332
- A closed instance object must not be used any further.
2333
-
2334
- ### sensorInstance.close()
2335
-
2336
- Closes the instance.
2337
-
2338
- ## sdl.audio
2339
-
2340
- ### Audio data
2341
-
2342
- 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.
2343
- The format of the data in these buffers depends on the options you passed to [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options).
2344
-
2345
- An audio buffer is a sequence of frames, and each frame is a sequence of samples.
2346
- A _sample_ is a single number representing the intensity of an audio channel at a point in time.
2347
- For audio with multiple channels, each point in time is represented by multiple samples (one per channel) that together make up a _frame_.
2348
- The samples in a frame are arranged as follows:
2349
-
2350
- - For 1 channel (mono) a frame contains just the one sample.
2351
- - For 2 channels (stereo) the frame contains two samples and the layout is: left, right. This means that the first sample corresponds to the left channel and the second sample corresponds to the right channel.
2352
- - For 4 channels (quad) the layout is front-left, front-right, rear-left, rear-right.
2353
- - For 6 channels (5.1) the layout is front-left, front-right, center, low-freq, rear-left, rear-right.
2354
-
2355
- So for example, to play 3 seconds of a 440Hz sine wave, you could do:
2356
-
2357
- ```js
2358
- const TWO_PI = 2 * Math.PI
2359
-
2360
- const {
2361
- channels,
2362
- frequency,
2363
- bytesPerSample,
2364
- minSampleValue,
2365
- maxSampleValue,
2366
- zeroSampleValue,
2367
- } = playbackInstance
2368
-
2369
- const range = maxSampleValue - minSampleValue
2370
- const amplitude = range / 2
2371
-
2372
- const sineAmplitude = 0.3 * amplitude
2373
- const sineNote = 440
2374
- const sinePeriod = 1 / sineNote
2375
-
2376
- const duration = 3
2377
- const numFrames = duration * frequency
2378
- const numSamples = numFrames * channels
2379
- const numBytes = numSamples * bytesPerSample
2380
- const buffer = Buffer.alloc(numBytes)
2381
-
2382
- let offset = 0
2383
- for (let i = 0; i < numFrames; i++) {
2384
- const time = i / frequency
2385
- const angle = time / sinePeriod * TWO_PI
2386
- const sample = zeroSampleValue + Math.sin(angle) * sineAmplitude
2387
- for (let j = 0; j < channels; j++) {
2388
- offset = playbackInstance.writeSample(buffer, sample, offset)
2389
- }
2390
- }
2391
-
2392
- playbackInstance.enqueue(buffer)
2393
- playbackInstance.play()
2394
- ```
2395
-
2396
- ### Sample formats
2397
-
2398
- String values used to represent how audio samples are stored in a Buffer.
2399
-
2400
- | Value | Corresponding `SDL_AudioFormat` | Comment |
2401
- | --- | --- | --- |
2402
- | `'s8'` | `AUDIO_S8` | signed 8-bit samples |
2403
- | `'u8'` | `AUDIO_U8` | unsigned 8-bit samples |
2404
- | `'s16lsb'` | `AUDIO_S16LSB` | signed 16-bit samples in little-endian byte order |
2405
- | `'s16msb'` | `AUDIO_S16MSB` | signed 16-bit samples in big-endian byte order |
2406
- | `'s16sys'` | `AUDIO_S16SYS` | signed 16-bit samples in native byte order |
2407
- | `'s16'` | `AUDIO_S16` | alias for `'s16lsb'` |
2408
- | `'u16lsb'` | `AUDIO_U16LSB` | unsigned 16-bit samples in little-endian byte order |
2409
- | `'u16msb'` | `AUDIO_U16MSB` | unsigned 16-bit samples in big-endian byte order |
2410
- | `'u16sys'` | `AUDIO_U16SYS` | unsigned 16-bit samples in native byte order |
2411
- | `'u16'` | `AUDIO_U16` | alias for `'u16lsb'` |
2412
- | `'s32lsb'` | `AUDIO_S32LSB` | 32-bit integer samples in little-endian byte order |
2413
- | `'s32msb'` | `AUDIO_S32MSB` | 32-bit integer samples in big-endian byte order |
2414
- | `'s32sys'` | `AUDIO_S32SYS` | 32-bit integer samples in native byte order |
2415
- | `'s32'` | `AUDIO_S32` | alias for `'s32lsb'` |
2416
- | `'f32lsb'` | `AUDIO_F32LSB` | 32-bit floating point samples in little-endian byte order |
2417
- | `'f32msb'` | `AUDIO_F32MSB` | 32-bit floating point samples in big-endian byte order |
2418
- | `'f32sys'` | `AUDIO_F32SYS` | 32-bit floating point samples in native byte order |
2419
- | `'f32'` | `AUDIO_F32` | alias for `'f32lsb'` |
2420
-
2421
- <a id="audio-event-deviceadd"></a>
2422
-
2423
- ### Event: 'deviceAdd'
2424
-
2425
- - `device: <object>`: An object from [`sdl.audio.devices`](#sdlaudiodevices) indicating the device that caused the event.
2426
-
2427
- Fired when a new audio device becomes available.
2428
- Check [`sdl.audio.devices`](#sdlaudiodevices) to get the new list of audio devices.
2429
-
2430
- <a id="audio-event-deviceremove"></a>
2431
-
2432
- ### Event: 'deviceRemove'
2433
-
2434
- - `device: <object>`: An object from [`sdl.audio.devices`](#sdlaudiodevices) indicating the device that caused the event.
2435
-
2436
- Fired when an existing audio device is removed.
2437
- Check [`sdl.audio.devices`](#sdlaudiodevices) to get the new list of audio devices.
2438
- When the `'deviceRemove'` event is emitted, all instances that were opened from the removed device are closed automatically.
2439
-
2440
- ### sdl.audio.bytesPerSample(format)
2441
-
2442
- - `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
2443
- - Returns: `<number>` The number of bytes.
2444
-
2445
- Helper function which maps each sample format to the corresponding number of bytes its samples take up.
2446
-
2447
- This function is also available from `@kmamal/sdl/helpers`.
2448
-
2449
- ### sdl.audio.minSampleValue(format)
2450
-
2451
- - `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
2452
- - Returns: `<number>` The minimum sample value.
2453
-
2454
- Helper function which maps each sample format to the corresponding minimum value its samples can take.
2455
-
2456
- This function is also available from `@kmamal/sdl/helpers`.
2457
-
2458
- ### sdl.audio.maxSampleValue(format)
2459
-
2460
- - `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
2461
- - Returns: `<number>` The maximum sample value.
2462
-
2463
- Helper function which maps each sample format to the corresponding maximum value its samples can take.
2464
-
2465
- This function is also available from `@kmamal/sdl/helpers`.
2466
-
2467
- ### sdl.audio.zeroSampleValue(format)
2468
-
2469
- - `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
2470
- - Returns: `<number>` The zero sample value.
2471
-
2472
- Helper function which maps each sample format to the sample value that corresponds to silence.
2473
-
2474
- This function is also available from `@kmamal/sdl/helpers`.
2475
-
2476
- ### sdl.audio.readSample(format, buffer[, offset])
2477
-
2478
- - `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
2479
- - `buffer: <Buffer>` The buffer to read the sample from.
2480
- - `offset: <number>` The position from which to read the sample. Default: `0`
2481
- - Returns: `<number>` The value of the sample read.
2482
-
2483
- Helper function which calls the appropriate `read*` method of `Buffer` based on the format argument.
2484
- For example, a call to `sdl.audio.readSample('f32', buffer, offset)` would be equivalent to `buffer.readFloatLE(offset)`.
2485
-
2486
- This function is also available from `@kmamal/sdl/helpers`.
2487
-
2488
- ### sdl.audio.writeSample(format, buffer, value[, offset])
2489
-
2490
- - `format: `[`<SampleFormat>`](#sample-formats): The desired sample format.
2491
- - `buffer: <Buffer>` The buffer to write the sample to.
2492
- - `value: <number>` The value of the sample to write.
2493
- - `offset: <number>` The position at which to write the sample. Default: `0`
2494
- - Returns: `<number>` The updated `offset`.
2495
-
2496
- Helper function which calls the appropriate `write*` method of `Buffer` based on the format argument.
2497
- For example, a call to `sdl.audio.writeSample('f32', buffer, value, offset)` would be equivalent to `buffer.writeFloatLE(value, offset)`.
2498
-
2499
- This function is also available from `@kmamal/sdl/helpers`.
2500
-
2501
- ### sdl.audio.devices
2502
-
2503
- - `<object>[]`
2504
- - `type: <string>` Either `'playback'` or `'recording'`.
2505
- - `name: <string>` The name of the device.
2506
-
2507
- A list of all the detected audio devices.
2508
- Sample output for PulseAudio:
2509
-
2510
- ```js
2511
- [
2512
- { name: 'Built-in Audio Analog Stereo', type: 'playback' },
2513
- { name: 'Built-in Audio Analog Stereo', type: 'recording' },
2514
- ]
2515
- ```
2516
-
2517
- Note that `sdl.audio.devices` may sometimes be an empty list.
2518
- Despite that, in many common cases, it's still possible to successfully open the default device by only passing `type` to [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) like this:
2519
-
2520
- ```js
2521
- const playbackInstance = sdl.audio.openDevice({ type: 'playback' })
2522
- ```
2523
-
2524
- ### sdl.audio.openDevice(device[, options])
2525
-
2526
- - `device: <object>` An object from [`sdl.audio.devices`](#sdlaudiodevices), or a custom device.
2527
- - `type: <string>`: Either `'playback'` or `'recording'`.
2528
- - `name: <string>|<null>`: The name of the device. Optional.
2529
- - `options: <object>`
2530
- - `channels: <number>`: Number of audio channels. Valid values: `1`, `2`, `4`, `6`. Default: `1`
2531
- - `frequency: <number>`: The sampling frequency in frames per second. Default: `48e3`
2532
- - `format: `[`<SampleFormat>`](#sample-formats): The binary format for each sample. Default: `'f32'`
2533
- - `buffered: <number>`: Number of frames buffered by the driver. Must be a power of `2`. Default: `4096`
2534
- - Returns: [`<AudioInstance>`](#class-audioinstance) an object representing the opened audio device instance.
2535
-
2536
- Initializes an audio device for playback/recording and returns a corresponding instance.
2537
- If the opened device is a playback device, then it returns an [`AudioPlaybackInstance`](#class-audioplaybackinstance-extends-audioinstance), otherwise it returns an [`AudioRecordingInstance`](#class-audiorecordinginstance-extends-audioinstance).
2538
-
2539
- Most of the time, you will be passing objects from [`sdl.audio.devices`](#sdlaudiodevices) for the `device` argument:
2540
-
2541
- ```js
2542
- const device = sdl.audio.devices[selectedIndex]
2543
- const playbackInstance = sdl.audio.openDevice(device)
2544
- ```
2545
-
2546
- It's also possible to let SDL pick the most appropriate device by only passing the `type` property:
2547
-
2548
- ```js
2549
- const playbackInstance = sdl.audio.openDevice({ type: 'playback' })
2550
- ```
2551
-
2552
- 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.
2553
- These drivers usually return an empty list for [`sdl.audio.devices`](#sdlaudiodevices).
2554
-
2555
- The `channels`, `frequency` and `format` options together define how the data is laid out in the `Buffer` objects that you write to playback instances of read from recording instances.
2556
- See also the section on [audio data](#audio-data).
2557
-
2558
- The `buffered` option specifies the "delay" between the application and the audio driver.
2559
- With smaller values you have smaller delays, but you also have to read/write data from/to the driver more frequently.
2560
- Applications such as virtual instruments that need to play audio in reaction to user input should set `buffered` to a lower value.
2561
-
2562
- ## class AudioInstance
2563
-
2564
- The `AudioInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
2565
- It only serves as the base class for [`AudioPlaybackInstance`](#class-audioplaybackinstance-extends-audioinstance) and [`AudioRecordingInstance`](#class-audiorecordinginstance-extends-audioinstance).
2566
-
2567
- <a id="audio-instance-event-close"></a>
2568
-
2569
- ### Event: 'close'
2570
-
2571
- Fired when the audio instance is about to close.
2572
- Handle cleanup here.
2573
-
2574
- ### audioInstance.id
2575
-
2576
- - `<number>`
2577
-
2578
- A unique identifier for the instance.
2579
-
2580
- ### audioInstance.device
2581
-
2582
- - `<object>`
2583
-
2584
- The device passed to [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) when the `audioInstance` was opened.
2585
-
2586
- ### audioInstance.channels
2587
-
2588
- - `<number>`
2589
-
2590
- The number of channels the instance was opened with.
2591
-
2592
- ### audioInstance.frequency
2593
-
2594
- - `<number>`
2595
-
2596
- The sampling frequency (in frames per second) the instance was opened with.
2597
-
2598
- ### audioInstance.format
2599
-
2600
- - [`<SampleFormat>`](#sample-formats)
2601
-
2602
- The audio sample format the instance was opened with.
2603
-
2604
- ### audioInstance.bytesPerSample
2605
-
2606
- - `<number>`
2607
-
2608
- The number of bytes that make up a single audio sample, based on the format the instance was opened with.
2609
-
2610
- ### audioInstance.minSampleValue
2611
-
2612
- - `<number>`
2613
-
2614
- The minimum value a sample can take, based on the format the instance was opened with.
2615
-
2616
- ### audioInstance.maxSampleValue
2617
-
2618
- - `<number>`
2619
-
2620
- The maximum value a sample can take, based on the format the instance was opened with.
2621
-
2622
- ### audioInstance.zeroSampleValue
2623
-
2624
- - `<number>`
2625
-
2626
- The sample value that corresponds to silence, based on the format the instance was opened with.
2627
-
2628
- ### audioInstance.readSample(buffer[, offset])
2629
-
2630
- - `buffer: <Buffer>` The buffer to read the sample from.
2631
- - `offset: <number>` The position from which to read the sample. Default: `0`
2632
- - Returns: `<number>` The value of the sample read.
2633
-
2634
- Helper function which calls the appropriate `read*` method of `Buffer` based on the format the instance was opened with.
2635
- 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)`.
2636
-
2637
- ### audioInstance.writeSample(buffer, value[, offset])
2638
-
2639
- - `buffer: <Buffer>` The buffer to write the sample to.
2640
- - `value: <number>` The value of the sample to write.
2641
- - `offset: <number>` The position at which to write the sample. Default: `0`
2642
- - Returns: `<number>` The updated `offset`.
2643
-
2644
- Helper function which calls the appropriate `write*` method of `Buffer` based on the format the instance was opened with.
2645
- 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)`.
2646
-
2647
- ### audioInstance.buffered
2648
-
2649
- - `<number>`
2650
-
2651
- The buffer size (in frames) the instance was opened with.
2652
-
2653
- ### audioInstance.playing
2654
-
2655
- - `<boolean>`
2656
-
2657
- Is `true` if the instance is currently playing.
2658
-
2659
- ### audioInstance.play([play])
2660
-
2661
- - `show: <boolean>` Set to `true` to start the instance, `false` to stop. Default: `true`
2662
-
2663
- Starts or stops the instance.
2664
-
2665
- ### audioInstance.pause()
2666
-
2667
- Equivalent to [`audioInstance.play(false)`](#audioinstanceplayplay)
2668
-
2669
- ### audioInstance.queued
2670
-
2671
- - `<number>`
2672
-
2673
- The number of bytes that are currently queued up, waiting to be either played by the system or dequeued by the user.
2674
-
2675
- ### audioInstance.clearQueue()
2676
-
2677
- Clears the queued data.
2678
-
2679
- ### audioInstance.closed
2680
-
2681
- - `<boolean>`
2682
-
2683
- Is `true` if the instance is closed.
2684
- A closed instance object must not be used any further.
2685
-
2686
- ### audioInstance.close()
2687
-
2688
- Closes the instance.
2689
-
2690
- ## class AudioPlaybackInstance extends AudioInstance
2691
-
2692
- The `AudioPlaybackInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
2693
- Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) are of type `AudioPlaybackInstance`, if a playback device is opened.
2694
-
2695
- ### playbackInstance.enqueue(buffer[, bytes])
2696
-
2697
- - `buffer: <Buffer>` The buffer to read data from.
2698
- - `bytes: <number>` The number of bytes to read from the buffer. Default: `buffer.length`
2699
-
2700
- Takes the audio data that you have written to the buffer, and writes it to the queue, from where it will be played back as audio.
2701
-
2702
- ## class AudioRecordingInstance extends AudioInstance
2703
-
2704
- The `AudioRecordingInstance` class is not directly exposed by the API so you can't (and shouldn't) use it with the `new` operator.
2705
- Instead, objects returned by [`sdl.audio.openDevice()`](#sdlaudioopendevicedevice-options) are of type `AudioRecordingInstance`, if a recording device is opened.
2706
-
2707
- ### recordingInstance.dequeue(buffer[, bytes])
2708
-
2709
- - `buffer: <Buffer>` The buffer to write data to.
2710
- - `bytes: <number>` The number of bytes to write to the buffer. Default: `buffer.length`
2711
- - Returns: `<number>` The actual number of bytes read.
2712
-
2713
- Takes recorded audio data that has is waiting on the queue, and writes it to the provided buffer.
2714
-
2715
- ## sdl.clipboard
2716
-
2717
- <a id="clipboard-event-update"></a>
2718
-
2719
- ### Event: 'update'
2720
-
2721
- Fired when the contents of the clipboard have changed.
2722
- Check [`sdl.clipboard.text`](#sdlclipboardtext) to get the new contents of the clipboard.
2723
-
2724
- ### sdl.clipboard.text
2725
-
2726
- - `<string>`
2727
-
2728
- The current text value on the clipboard.
2729
-
2730
- ### sdl.clipboard.setText(text)
2731
-
2732
- - `text: <string>` The new value to save on the clipboard.
2733
-
2734
- Changes the text contents of the clipboard.
2735
-
2736
- ## sdl.power
2737
-
2738
- ### sdl.power.info
2739
-
2740
- - `<object>`
2741
- - `state: <string>|<null>` One of `'noBattery'`, `'battery'`, `'charging'`, `'charged'`. Is `null` if it can't be determinded.
2742
- - `seconds: <number>|<null>` Seconds of battery life left, or `null` if not running on battery or if it can't be determinded.
2743
- - `percent: <number>|<null>` Percentage of battery life left, or `null` if not running on battery or if it can't be determinded.
2744
-
2745
- The curent power information of the device.
2746
-
2747
- ## Helpers
2748
-
2749
- The `@kmamal/sdl` library must only be imported from the main thread.
2750
- If you try importing it from a `worker_thread` you will get an error.
2751
- This is mainly due to some limitations in SDL itself (it's often unsafe to call functions from threads other than the one that called `SDL_Init`) as well as Node.js native modules (each thread gets its own instance of the module and it's hard to make them talk with each other).
2752
-
2753
- It's often useful however to offload CPU-heavy work to a thread, so the main thread can respond to input events faster.
2754
- This is still possible!
2755
- Even if the threads do not have access to the SDL-related functions, they can still write data to buffers and then pass those buffers to the main thread from where they can be passed to SDL.
2756
- One thing is missing: While the core of the library is not needed, it's nice to have the helper functions, for example when writing an audio renderer it's nice to have the [`readSample`](#sdlaudioreadsampleformat-buffer-offset), [`writeSample`](#sdlaudiowritesampleformat-buffer-value-offset), etc functions.
2757
-
2758
- Since these are just helpers and don't call any SLD code underneath it's safe to use them.
2759
- They are made available through the `@kmamal/sdl/helpers` sub-module that does not load any of the native code.
2760
- For an example of their use see [this example](https://github.com/kmamal/node-sdl/blob/master/examples/12-audio-thread/audio-worker.js).
2761
-
2762
- The functions included in `@kmamal/sdl/helpers` are:
2763
-
2764
- - [`sdl.audio.bytesPerSample`](#sdlaudiobytespersampleformat)
2765
- - [`sdl.audio.minSampleValue`](#sdlaudiominsamplevalueformat)
2766
- - [`sdl.audio.maxSampleValue`](#sdlaudiomaxsamplevalueformat)
2767
- - [`sdl.audio.zeroSampleValue`](#sdlaudiozerosamplevalueformat)
2768
- - [`sdl.audio.readSample`](#sdlaudioreadsampleformat-buffer-offset)
2769
- - [`sdl.audio.writeSample`](#sdlaudiowritesampleformat-buffer-value-offset)
2770
-
2771
- ## Building from source
2772
-
2773
- If prebuilt binaries are not available for your platform, `@kmamal/sdl` tries to compile itself during installation.
2774
- A few prerequisites are necessary for that to work:
2775
-
2776
- First, install [node-addon-api](https://github.com/nodejs/node-addon-api) and [node-gyp](https://github.com/nodejs/node-gyp#installation) with all its dependencies.
2777
-
2778
- On Mac, you also need to install `xquartz` so that SDL can find the X11 headers it needs.
2779
- The command to install `quartz` via homebrew is `brew install xquartz`.
2780
-
2781
- You don't need to install any SDL libraries or headers.
2782
- These are downloaded automatically through the [@kmamal/build-sdl](https://github.com/kmamal/build-sdl) package.
2783
- If `@kmamal/build-sdl` has no prebuilt library for your platform, it tries to compile one on the spot.
2784
- You need to have `cmake` installed for that to work.
2785
-
2786
- ---
2787
-
2788
- You could also have found your way to the "Building from source" section because you are trying to contribute to this package.
2789
- There are some npm scripts in `package.json` that could be of use to you:
2790
-
2791
- - `npm run clean` deletes all folders that are created during the build, as well as `node_modules`.
2792
- - `npm run download-release` downloads the prebuilt binaries. This is the first thing the install script tries to do.
2793
- - `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.
2794
- - `npm run build` prepares the environment variables and calls `node-gyp` to build the package.
2795
- - `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.
137
+ # Documentation
2796
138
 
2797
- The SDL headers and libs get downloaded to `sdl/`, the build happens in `build/`, and the final binaries get collected into `dist/`.
139
+ The full [API Reference](https://github.com/kmamal/node-sdl/tree/master/docs/api-reference.md) documents every function.
2798
140
 
2799
- 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` to re-build the package.
141
+ To get started, browse the [examples](https://github.com/kmamal/node-sdl/tree/master/examples#readme) in the repo.
2800
142
 
2801
- Have fun!