@kmamal/sdl 1.0.0-2 → 1.0.0-3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,252 +7,114 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
- See the [migration guide](https://github.com/kmamal/node-sdl/tree/master/docs/migrating-to-sdl3.md) for a walkthrough of the breaking changes.
10
+ ## [v1.0.0] - 2026-10-01
11
+
12
+ The library now builds against SDL3 (3.4.x) instead of SDL2. This release contains breaking changes, see the [migration guide](https://github.com/kmamal/node-sdl/tree/master/docs/migrating-to-sdl3.md) for a walkthrough.
11
13
 
12
14
  ### Changed
13
15
 
14
- - **Breaking:** The library now builds against SDL3 (3.4.x) instead of SDL2. Most of the JS API is unchanged, but some values shifted with SDL's own changes:
15
- - Audio: sample formats follow SDL3's names: `s16le`/`s16be`, `s32le`/`s32be`, and `f32le`/`f32be` replace the `lsb`/`msb` variants, and the unsuffixed `s16`, `s32`, and `f32` now mean native byte order (replacing the `sys` variants) instead of aliasing little-endian. The unsigned 16-bit sample formats (`u16`, `u16lsb`, `u16msb`, `u16sys`) are gone — SDL3 removed them. Internally the queue-based device API was replaced with SDL3 audio streams (see the audio API entry below for the resulting renames).
16
- - Keyboard: the scancodes SDL3 removed are gone from `sdl.keyboard.SCANCODE` (`AUDIOMUTE`, `WWW`, `MAIL`, `CALCULATOR`, `COMPUTER`, `BRIGHTNESSDOWN/UP`, `DISPLAYSWITCH`, `KBDILLUM*`, `APP1`, `APP2`), and so are the corresponding key names. The media scancodes follow SDL3's names (`MEDIA_PLAY`, `MEDIA_NEXT_TRACK`, `MEDIA_PREVIOUS_TRACK`, `MEDIA_STOP`, `MEDIA_REWIND`, `MEDIA_FAST_FORWARD`, `MEDIA_EJECT`, `MEDIA_SELECT` instead of `AUDIOPLAY`, `AUDIONEXT`, …), and so do the key names (`mediaPlay`, `mediaTrackNext`, `mediaTrackPrevious`, `mediaStop`, `mediaRewind`, `mediaFastForward` instead of `audioPlay`, `audioNext`, …).
17
- - Joystick/gamepad: the power level strings are gone. `power` (and the `powerUpdate` event) now report SDL3's power info directly as `{ state, percent }`, in the same format as `sdl.power.info`. Gamepad types `'virtual'`, `'amazonLuna'`, `'googleStadia'`, and `'nvidiaShield'` no longer exist (SDL3 reports such devices as generic gamepads); `'gamecube'` is new.
18
- - Sensors: `data.timestamp` is gone — SDL3 removed the timestamped read.
19
- - Displays: `dpi` is replaced by `scale`, SDL3's unitless content scale (`1` is the 96dpi baseline). Displays now carry a stable `id`, which is what hot-plug events and `createWindow({ display })` go by; a display that is disconnected and reconnected is a new device rather than a match for the old one.
20
- - Audio: devices now carry a stable `id`, and are opened by that id instead of by `name`. Opening arbitrary driver-specific device names is no longer possible, since SDL3 only opens devices it has enumerated.
21
- - Enum strings follow SDL3's names: cursors are `default`, `text`, `progress`, `nwseResize`, `neswResize`, `ewResize`, `nsResize`, `move`, `notAllowed`, and `pointer` (instead of `arrow`, `ibeam`, `waitarrow`, `sizenwse`, `sizenesw`, `sizewe`, `sizens`, `sizeall`, `no`, and `hand`); joystick types are `arcadeStick`, `flightStick`, `dancePad`, `drumKit`, and `arcadePad`; and diagonal hat positions are `rightUp`, `rightDown`, `leftUp`, and `leftDown`.
22
- - Pixel formats follow SDL3's names, which spell out the unused byte: `xrgb4444`, `xrgb1555`, `xbgr1555`, `xrgb8888`, and `xbgr8888` replace `rgb444`, `rgb555`, `bgr555`, `rgb888`, and `bgr888`.
23
- - Windows: the X11-only `skipTaskbar`, `popupMenu`, `tooltip`, and `utility` options of `createWindow()` and the matching `window` getters are removed. SDL3 requires a parent window for popup menus and tooltips, and hides the taskbar entry only through the utility flag. The `scaling: 'best'` render mode is gone, since SDL3 only offers `'nearest'` and `'linear'`.
24
- - **Breaking:** The audio API follows SDL3's model of separate playback and recording devices and of audio streams. `sdl.audio.devices` and `sdl.audio.openDevice()` are replaced by `sdl.audio.playback` and `sdl.audio.recording`, each with its own `devices` list, `openDevice([device[, options]])` function, and `deviceAdd`/`deviceRemove` events; device objects lose their `type`, each list starts with a default-device entry whose `id` is `null`, and passing no device (or `null`) opens that default device. `AudioInstance`, `AudioPlaybackInstance`, and `AudioRecordingInstance` are now `AudioStream`, `AudioPlaybackStream`, and `AudioRecordingStream`: `enqueue()` is `putData()`, `dequeue()` is `getData()`, `clearQueue()` is `clear()`, recording streams report `available` instead of `queued`, `device` is the default-device entry for streams opened on the default device, the redundant `name` property is gone, and `buffered` moved from the stream to its device.
25
- - **Breaking:** `sdl.controller` is now `sdl.gamepad`, following SDL3's rename: `ControllerInstance` is `GamepadInstance`, the `'gamecontroller'` joystick type is `'gamepad'`, and `sdl.info.initialized.controller` is `sdl.info.initialized.gamepad`. Buttons follow SDL3's position-based names: the face buttons are `south`, `east`, `west`, and `north` (instead of `a`, `b`, `x`, `y`), and the paddles are `rightPaddle1`, `leftPaddle1`, `rightPaddle2`, and `leftPaddle2` (instead of `paddle1` through `paddle4`).
26
- - **Breaking:** Mouse coordinates are floating point, as in SDL3: the positions on `mouseMove`, `mouseButtonDown`/`mouseButtonUp`, and `mouseWheel` events and in `sdl.mouse.position` may be fractional on high-DPI displays and on backends that report sub-pixel pointer positions, so round them where integers are needed. In the other direction, `sdl.mouse.setPosition()` and the `dstRect` option of `window.render()` accept fractional values, the latter positioning the image at sub-pixel precision.
27
- - **Breaking:** Touch device `id`s and the `fingerId` on touch events are now `bigint`s. They are 64-bit values in SDL, which a JS `number` can't always represent exactly.
28
- - **Breaking (Linux):** `window.native.handle` now holds a tagged `{ subsystem, display, window }` struct instead of a bare X11 window id, and the internal payloads passed to `@kmamal/gl`/`@kmamal/gpu` changed the same way. Older versions of those packages can't consume the new payload — upgrade them together with this one.
29
- - Declared support for Node.js >= 22 in `package.json`, and pinned the native addon to the matching Node-API version 9.
30
- - **Breaking:** The space key is now reported as `' '`, like every other character-producing key, instead of `'space'`.
31
- - **Breaking:** Joystick axes are now normalized relative to the axis's true center, like gamepad axes, instead of relative to whatever value the axis had when the device was opened. Pedals and throttles that rest at one end of their range now read `1` or `-1` at rest instead of `0`, and axes that rest at their maximum no longer report `NaN`.
32
- - **Breaking:** `window.setFullscreen()`, `window.minimize()`, `window.maximize()`, and `window.restore()` follow SDL3's asynchronous model: they submit a request to the windowing system and return, and `fullscreen`, `minimized`, and `maximized` update once the change has taken effect (or not at all, if the windowing system denies it). Code that read those properties right after the call should listen for the `minimize`/`maximize`/`restore` events or poll instead. `maximize()` now throws on a non-resizable window, which SDL3 refuses to maximize.
33
- - **Breaking:** `window.setPosition()`, `window.setSize()`, and `window.setSizeInPixels()` follow the same asynchronous model: `x`, `y`, `width`, `height`, `pixelWidth`, and `pixelHeight` update from the `move` and `resize` events once the windowing system has applied the change, instead of being set to the requested values right away. The requested values were often never taken, for example on fullscreen and maximized windows, or under window managers that adjust or refuse the request. Code that read those properties right after the call should listen for the `move`/`resize` events or poll instead.
34
- - **Breaking:** The `duration` of `rumble()` and `rumbleTriggers()` now defaults to `null`, which rumbles until stopped, instead of `1e3`; pass `1e3` explicitly for the old behavior. A duration of `0` is now rejected; it used to stop the rumble right away.
35
- - **Breaking:** `createWindow()` now throws if the `accelerated` or `vsync` option is given together with `opengl` or `webgpu`, instead of silently ignoring it. OpenGL and WebGPU windows have no SDL renderer, so `window.accelerated` and `window.vsync` are now `null` for them instead of echoing the options.
36
- - Range errors now state the violated constraint (e.g. "width must be a positive 32-bit integer", "device must be from sdl.joystick.devices") instead of a generic "invalid width" or "invalid device".
16
+ - Exceptions thrown in event listeners are re-emitted as an `'error'` event on the window or instance, following the usual `EventEmitter` semantics: with no `'error'` listener they surface as an uncaught exception. They no longer stop event delivery or crash the process.
17
+ - Attaching a listener to a destroyed window or a closed instance or stream now throws, instead of silently never firing.
18
+ - Audio and video formats are reported using the platform-independent enums. The platform-dependent ones are only used as input.
19
+ - Character keys are reported as the unshifted character (`'ü'` instead of `'Ü'`), so `getKey(getScancode('ü'))` round-trips.
20
+ - steamHandle is now reported as a BigInt.
37
21
 
38
22
  ### Added
39
23
 
40
- - Native window handles under the Wayland video driver (`SDL_VIDEODRIVER=wayland`). `window.native` now carries valid Wayland objects instead of garbage reinterpreted as X11 handles, and a new `window.native.subsystem` field (`'x11'` or `'wayland'`, Linux only) says which kind you're holding. Any other Linux video driver now yields `handle: null` and a clear error for `opengl`/`webgpu` windows.
41
- - Relative mouse mode for FPS-style camera controls, via `window.setRelativeMouseMode()`, `window.unsetRelativeMouseMode()`, and `window.relativeMouseMode`.
42
- - `sdl.video` events `'displayScaleChange'`, `'displayModeChange'`, and `'displayUsableChange'`, fired when a display's content scale, current mode, or usable region changes. The display objects in `sdl.video.displays` are updated accordingly, where before `scale`, `format`, `frequency`, and `usable` were only read at startup.
43
- - `sdl.mouse.captured`, reporting whether a mouse capture has been requested with `sdl.mouse.capture()`, and `window.mouseCaptured`, reporting whether the window currently holds the capture.
44
- - Audio device objects report the `format`, `channels`, `frequency`, and `buffered` the device itself is running with while streams are open on them, and `null` otherwise. SDL converts between each stream's format and its device's, so these may differ from the stream's own.
45
- - `mouseMove` events now report the mouse's relative movement through `dx` and `dy`.
46
- - `ballMotion` events now report the ball's relative movement through `dx` and `dy`, alongside the accumulated `x` and `y` position.
47
- - Pixel-format helpers `sdl.video.bytesPerPixel()`, `sdl.video.isYuv()`, `sdl.video.isPlanarYuv()`, and `sdl.video.minBufferSize()`, mirroring the existing audio sample-format helpers.
48
- - `@kmamal/sdl/helpers` now also exposes the pixel-format helpers and the `keyboard.SCANCODE`, `mouse.BUTTON`, and `sensor.STANDARD_GRAVITY` constants, under the same paths as in the main module.
49
- - Prebuilt binaries for Windows on arm64.
50
- - `NODE_SDL_SYSTEM=1 npm install` builds against the SDL already installed on the system (located through `pkg-config`, or through `SDL_INC`/`SDL_LIB` when set) instead of downloading one, and links to it at runtime rather than bundling a copy. This is for platforms without prebuilt binaries, cross-compilation sysroots, and distribution packaging.
51
- - `gamepadInstance.buttonLabels`, reporting the label printed on each face button (`'a'`, `'cross'`, ...), so the position-named buttons can still be shown to the user by name.
52
- - Gamepad buttons `misc2` through `misc6`, and the `'standard'` gamepad type for generic gamepads that used to report `null`.
53
- - The single-edge and corner resize cursors SDL3 added (`nResize`, `neResize`, `eResize`, `seResize`, `sResize`, `swResize`, `wResize`, `nwResize`), and the `X1` and `X2` mouse buttons in `sdl.mouse.BUTTON`.
54
- - Audio streams can be opened with any number of channels from `1` to `8`, covering the 2.1, 4.1, 6.1, and 7.1 layouts SDL3 supports, instead of only `1`, `2`, `4`, or `6`.
55
- - The pixel formats SDL3 added: `xbgr4444`, `xrgb2101010`, `xbgr2101010`, `abgr2101010`, the 16-bit-per-channel integer formats (`rgb48`, `bgr48`, `rgba64`, `argb64`, `bgra64`, `abgr64`), the 16-bit float formats (`rgb48f`, `bgr48f`, `rgba64f`, `argb64f`, `bgra64f`, `abgr64f`), the 32-bit float formats (`rgb96f`, `bgr96f`, `rgba128f`, `argb128f`, `bgra128f`, `abgr128f`), the `rgbx32`/`xrgb32`/`bgrx32`/`xbgr32` byte-order aliases, and the `p010` YUV format (which `window.render()` rejects, since SDL's renderer can't display it).
56
- - Gamepad buttons `misc1` (the Xbox Series X share button, PS5 microphone button, Switch Pro capture button, or Luna microphone button) and `touchpad` (PS4/PS5 touchpad click). They used to arrive as `buttonDown`/`buttonUp` events with `button: null` and pollute `gamepadInstance.buttons` with a `null` key.
57
- - Scancodes `SOFTLEFT`, `SOFTRIGHT`, `CALL`, and `ENDCALL`, and the corresponding `'softLeft'`, `'softRight'`, `'call'`, and `'endCall'` keys.
58
- - Scancodes `WAKE`, `CHANNEL_INCREMENT`, `CHANNEL_DECREMENT`, `MEDIA_PAUSE`, `MEDIA_RECORD`, `MEDIA_PLAY_PAUSE`, and `AC_NEW` through `AC_PROPERTIES`, and the corresponding `'wake'`, `'channelUp'`, `'channelDown'`, `'mediaPause'`, `'mediaRecord'`, `'mediaPlayPause'`, `'new'`, `'open'`, `'close'`, `'exit'`, `'save'`, `'print'`, and `'properties'` keys.
59
- - The keys SDL3 reports through its extended keycodes: `'compose'`, `'meta'`, `'hyper'`, and `'leftTab'`. They used to come out as `null`.
60
- - The keys `'international2'`, `'international4'`, `'international5'`, and `'language1'` through `'language4'`, found on Japanese and Korean keyboards. They used to come out as `null`.
61
- - Mouse and finger events have a `pen` flag, set when SDL synthesized the event from pen input.
62
- - Window event `'fingerCancel'`, fired when the system cancels a touch instead of lifting the finger. SDL3 reports these separately from `fingerUp`, and they used to be dropped.
24
+ - Windows arm64 build
25
+ - Wayland support
26
+ - Support FreeBSD, OpenBSD, and NetBSD.
27
+ - `NODE_SDL_SYSTEM=1 npm install` builds against the SDL already installed on the system (located through `pkg-config`, or `SDL_INC`/`SDL_LIB`) instead of downloading one.
28
+ - Relative mouse mode for FPS-style camera controls.
29
+ - `mouseMove` and `ballMotion` events report relative movement through `dx` and `dy`.
30
+ - Window event `'fingerCancel'`, fired when the system cancels a touch.
31
+ - Audio device objects report the `format`, `channels`, `frequency`, and `buffered` the device is running with while streams are open on them.
32
+ - Gamepad buttons `misc1` and `touchpad` are now reported instead of arriving with `button: null`.
33
+ - Pixel-format helpers similar to audio format helpers.
34
+ - More stuff in `@kmamal/sdl/helpers`
35
+ - More scancodes and keys
63
36
 
64
37
  ### Fixed
65
38
 
66
- Windows and events:
67
-
68
- - A new window's initial position, size, pixel size, display, and flags are now read after the window is shown, so they include whatever the windowing system applied on showing it. They, and the initial `move` and `resize` events, used to report the pre-show values when the window was created from inside an event listener, since the real events from showing it were then dropped.
69
- - `resize` now also fires, and `pixelWidth`/`pixelHeight` update, when only the window's pixel size changes (for example when it moves to a display with a different scale). SDL3 reports that separately from a logical resize, and it used to be dropped.
70
- - `window.setPosition()` now throws when the windowing system can't position the window (regular windows under Wayland), and the other window setters (`setTitle()`, `setSize()`, `setResizable()`, `setBorderless()`, `show()`, `hide()`, `focus()`) throw if SDL reports a failure. The error used to be ignored and left pending, where later calls reported it as a spurious "SDL silent error".
71
- - `window.focus()` no longer marks the window as focused before the windowing system has honored the request. `focused` updates on the `focus` event, as it does for every other focus change.
72
- - `window.setIcon()` now throws when the windowing system refuses the icon (Wayland, for example) instead of silently doing nothing.
73
- - `window.render()` now reports a proper "options must be an object" error for a non-object `options` argument instead of a bare `TypeError`.
74
- - `window.fullscreen` now tracks SDL's own enter/leave-fullscreen notifications. It used to be reset to `false` whenever the window was minimized, maximized, or restored, although SDL keeps a fullscreen window fullscreen across those (a fullscreen window that is minimized on focus loss and then restored comes back fullscreen). `minimized`, `maximized`, and `visible` likewise no longer guess: they only change when the windowing system reports the change, so a `minimize()` request that the window manager ignores is no longer reported as minimized.
75
- - `move` and `resize` events are no longer delivered twice, including when a listener moves or resizes the window.
76
- - An exception thrown in an event listener no longer permanently stops event delivery, and no longer crashes the process when it happens in a `move` or `resize` listener while the window is being dragged. Listener exceptions are now re-emitted as an `'error'` event on the window or instance, following the usual `EventEmitter` semantics: with no `'error'` listener they surface as an uncaught exception.
77
- - Calling `window.destroy()` from a `move` or `resize` listener that fires while the window is being dragged or resized no longer risks a crash. The window reports `destroyed` immediately, and the native window is destroyed once it is safe to do so.
78
- - Calling `window.destroy()` from a `beforeClose` listener no longer crashes the process. `destroyGently()` used to call `destroy()` afterwards anyway, and the resulting "window is destroyed" error propagated out of the event poll loop as an uncaught exception.
79
- - Removing all of a window's listeners (whether via `removeAllListeners()` or one `removeListener()` at a time) no longer breaks event polling, no longer lets the process exit while the window is still open, and no longer turns `window.destroy()` into a silent no-op. It used to also remove the internal keep-alive listener.
80
- - Listening for `newListener` or `removeListener` no longer engages fast event polling that keeps the process alive and could never be turned back off.
81
- - `emit()` on windows and instances now returns whether the event had listeners, as the `EventEmitter` contract specifies, instead of `undefined`.
82
- - A `close` listener that throws (with no `error` listener to catch it) no longer leaves the destroyed window's or closed instance's listeners registered, which kept event polling engaged and the process alive forever.
83
- - Attaching a listener to a destroyed window or a closed instance or stream now throws. Such a listener could never fire and was never removed, so it kept event polling engaged and the process alive forever.
84
- - Closing the last window via its close button no longer fires `beforeClose` twice. SDL used to follow the window's close event with a quit event, and the quit handling asked the same window to close again, so a listener that called `prevent()` was bypassed on the second round.
85
- - Windows now report their actual size on creation (a fullscreen window no longer reports the default 640x480).
86
- - The initial `resize` event is no longer delivered to windows destroyed in the same tick they were created.
87
- - Windows created with `visible: false` no longer receive an initial `expose` event. They get one from SDL once they are shown.
88
- - `window.setSizeInPixels()` now converts the size using the window's actual pixel density and rounds to the nearest size in points, instead of deriving the ratio from the window's rounded current sizes. It used to reject almost every size on displays with a fractional scale (at 150%, even `1920×1080` threw "must be a multiple of 1.5005…").
89
- - `setResizable()` and `setBorderless()` now enforce the same mutual exclusivity that `createWindow()` does, instead of letting the invariant be bypassed after creation.
90
- - `window.render()` now throws if updating the texture fails instead of silently presenting stale contents.
91
- - `window.render()`, `mouse.setCursor()`, `mouse.setCursorImage()`, `mouse.resetCursor()`, and `mouse.redrawCursor()` now throw if SDL fails to present the frame or apply the cursor, instead of ignoring the failure and leaving its error pending.
92
- - A failure to recreate the render texture (such as an oversized `render()`) no longer leaves a dangling texture pointer that corrupts memory on later calls, and destroying a window whose renderer could not be rebuilt (after a failed `setVsync()` or `setAccelerated()` call) no longer leaks its texture.
93
- - `window.render()` on a window left without a renderer by a failed `setVsync()` or `setAccelerated()` call now throws "window has no renderer" instead of an error with an empty message.
94
- - `sdl.mouse.resetCursor()` without a video subsystem, and joystick, gamepad, and sensor calls on a device SDL no longer has open, now throw a descriptive error instead of one with an empty message.
95
- - Renderer error messages now include the flag values instead of pointer addresses.
96
- - Image `stride` and buffer sizes are now validated in bytes, preventing out-of-bounds reads in native code. For the planar YUV formats the check also accounts for SDL rounding the chroma planes up, so odd dimensions no longer read out of bounds either, and for the packed YUV formats (`yuy2`, `uyvy`, `yvyu`) the minimum stride of an odd-width image covers the full last 4-byte pixel pair SDL reads.
97
- - `window.setIcon()` and `mouse.setCursorImage()` now reject YUV pixel formats with a clear validation error. SDL cannot create surfaces from them, so they always failed — but with a cryptic native error.
98
- - A `blur` or `leave` event no longer clears `sdl.video.focused`/`sdl.video.hovered` when another window has already gained focus or hover.
99
- - `sdl.video.focused` and `sdl.video.hovered` now pump events first, like the per-window getters, instead of returning stale values.
100
- - Attaching a listener to a destroyed window or a closed instance or stream now throws right away, as documented, instead of being silently accepted and dropped at the end of the tick.
101
- - On macOS, `webgpu` windows now install their Metal layer before making the view layer-backed, the order AppKit requires for a view to host its own layer. The layer could otherwise be replaced by AppKit and stop showing the rendered frames.
39
+ Windows:
40
+
41
+ - A new window reports its actual position, size, display, and flags on creation (a fullscreen window no longer reports 640x480), including when it is created from inside an event listener.
42
+ - OpenGL and WebGPU windows have no SDL renderer, so `createWindow()` now throws if you pass `accelerated` or `vsync` together with `opengl` or `webgpu`, instead of ignoring the option.
43
+ - `resize` fires, and `pixelWidth`/`pixelHeight` update, when only the pixel size changes (for example when moving to a display with a different scale).
44
+ - `move` and `resize` events are no longer delivered twice.
45
+ - Closing the last window via its close button no longer fires `beforeClose` twice, which bypassed `prevent()`.
46
+ - Windows created with `visible: false` no longer receive an initial `expose` event until they are shown.
47
+ - `window.fullscreen`, `minimized`, `maximized`, `visible`, and `focused` only change when the windowing system reports the change.
48
+ - `fullscreen` is no longer reset when the window is minimized, maximized, or restored.
49
+ - `window.setSizeInPixels()` no longer rejects almost every size on displays with a fractional scale.
50
+ - `setResizable()` and `setBorderless()` enforce the same mutual exclusivity as `createWindow()`.
51
+ - `window.destroy()` no longer crashes when called from a `beforeClose` listener, or from a `move` or `resize` listener while the window is being dragged.
52
+ - Removing all of a window's listeners no longer breaks event polling, lets the process exit while the window is open, or turns `destroy()` into a no-op.
53
+ - `window.render()` throws instead of silently presenting stale contents when updating the texture fails, and no longer corrupts memory or leaks after a failed render or renderer switch.
54
+ - Windows recover from a lost graphics device instead of failing every `render()` from then on.
55
+ - `window.render()` validates image `stride` and buffer sizes, preventing out-of-bounds reads, including for planar and packed YUV formats with odd dimensions.
56
+ - `window.setIcon()` and `mouse.setCursorImage()` reject YUV pixel formats with a clear error.
57
+ - A `blur` or `leave` event no longer clears `sdl.video.focused`/`sdl.video.hovered` when another window has already gained focus or hover, and both now return current values.
102
58
 
103
59
  Displays:
104
60
 
105
- - Connecting or disconnecting a display no longer crashes the process, including when the display disappears while its hot-plug, orientation, or move event is being processed.
106
- - Displays are now looked up by their stable id instead of their position in `sdl.video.displays`, which diverged when a display vanished mid-enumeration. `displayOrient`/`displayMove` events used to update and report the wrong display, `createWindow()` with the `display` option could open the window on the wrong display, and `window.display` could return the wrong one. `window.display` (and the `display` on `displayChange` events) is now `null` when the window's display has been removed.
107
- - `createWindow()` now requires the `display` option to be one of the objects in `sdl.video.displays` and throws otherwise, instead of matching by name (which identical monitors share) and silently falling back to the first display when nothing matched.
108
- - The `displayMove` event is now emitted instead of throwing "invalid event", and both `displayOrient` and `displayMove` events now carry the documented `device` property.
109
- - `sdl.video.displays` now returns a copy of the display list, so modifying it no longer corrupts the library's internal state.
110
- - Display modes with a 32-bit RGBA pixel format now report it under its `*8888` name (such as `'argb8888'`) instead of the endianness-dependent `*32` alias (such as `'bgra32'`). The two are the same SDL format, but the `*8888` names were documented as possible values and could never actually appear.
111
- - A display's `frequency` (and the `frequency` on `displayModeChange` events) is now `null` when SDL doesn't know the refresh rate, instead of `0`.
61
+ - Connecting or disconnecting a display no longer crashes the process.
62
+ - `window.display` is `null` when its display has been removed.
63
+ - The `displayMove` event is emitted instead of throwing "invalid event", and `displayOrient` and `displayMove` events carry the documented `device` property
64
+ - A display's `frequency` is `null` instead of `0` when the refresh rate is unknown.
112
65
 
113
66
  Mouse and keyboard:
114
67
 
115
- - `mouseWheel` events now report the mouse position at the time of the event, carry precise fractional `dx`/`dy` values so high-resolution trackpad scrolls no longer arrive as `0`, and have a boolean `flipped` property.
116
- - `mouse.getButton()` now pumps events first, so it returns the current button state instead of values up to a second old. It also accepts the correct button range, and no longer relies on undefined behavior for button 32.
117
- - The right GUI key now reports the documented `'gui'` key name instead of `'gUI'`.
118
- - The GUI keys on Windows and the GUI and Alt keys on macOS now report the platform's names for them, `'windows'`, `'command'`, and `'option'`, instead of `null`. `sdl.keyboard.getScancode()` accepts these names on the corresponding platforms.
119
- - `sdl.keyboard.getScancode()` now resolves single-character keys such as `','` and `'0'` to the main keyboard keys instead of the keypad ones.
120
- - Keys whose character lies outside the Basic Multilingual Plane (such as emoji) are now reported as that character instead of `null`, and `sdl.keyboard.getScancode()` accepts them instead of throwing "invalid key".
121
- - `sdl.info.platform` is `'macOS'` on macOS, following SDL3's platform name. It used to be documented and typed as `'Mac OS X'`, which SDL3 no longer reports.
122
- - `sdl.info.platform` is now documented and typed with every platform name SDL3 can report (such as `'FreeBSD'` for builds from source), instead of only `'Linux'`, `'Windows'`, and `'macOS'`, and is `null` instead of SDL's `'Unknown (see SDL_platform.h)'` placeholder when SDL doesn't know the platform.
123
- - Keys whose SDL3 default name differs from the X11 one (`'+/-'`, `'modeSwitch'`, `'('`, `')'`, and the menu key) are recognized again on every platform. Their default names had been dropped from the key table during the migration, so they came out as `null` outside X11.
124
- - `sdl.keyboard.getKey()` now agrees with the `key` of keyboard events on layouts where SDL's keycode options apply. On AZERTY the number row maps to `'1'`…`'0'` instead of `'&'`, `'é'`, …, and on non-Latin layouts the letter keys map to `'a'`…`'z'`, as they do in events.
125
- - Character keys are now reported as the unshifted character SDL assigns to them. SDL3 names non-ASCII letters by their capital, so `ü` used to arrive as `'Ü'`, and `getKey(getScancode('ü'))` did not round-trip.
126
- - `sdl.keyboard.getKey()` and `getScancode()` now pick up a keyboard layout change right away. They used to keep answering with the old layout until the next event poll.
68
+ - The space key is reported as `' '`, like every other character-producing key, instead of `'space'`.
69
+ - `mouse.getButton()` returns the current button state instead of old values.
70
+ - The right GUI key reports the documented `'gui'` key name instead of `'gUI'`.
71
+ - The GUI keys on Windows and the GUI and Alt keys on macOS report `'windows'`, `'command'`, and `'option'` instead of `null`.
72
+ - Keys outside the Basic Multilingual Plane (such as emoji) are reported as that character instead of `null`.
73
+ - `sdl.keyboard.getScancode()` resolves single-character keys such as `','` and `'0'` to the main keyboard keys instead of the keypad ones.
74
+ - `sdl.keyboard.getKey()` agrees with the `key` of keyboard events on AZERTY and non-Latin layouts, and both functions pick up a layout change right away.
127
75
 
128
76
  Touch:
129
77
 
130
- - Touch events no longer crash event handling. Events synthesized from the mouse arrive with a `null` `device`, and events for a device that disconnected before they were polled are dropped.
131
- - `sdl.touch.devices` now refetches the device list on every read. It used to return the list from module load time forever, since SDL emits no touch hot-plug events that could refresh it. Device objects remain valid across reads, like the sensor device objects, so they can be compared with the `device` of touch events, and the returned list is a copy, so modifying it no longer corrupts the library's internal state.
132
- - `sdl.touch.devices` no longer lists the virtual touch devices SDL creates for touch events it synthesizes from the mouse and pen, and finger events synthesized from a pen arrive with a `null` `device`, like the ones synthesized from the mouse.
78
+ - Touch events no longer crash event handling.
79
+ - `sdl.touch.devices` is refreshed on every read instead of returning the list from startup, and no longer lists the virtual devices SDL creates for events synthesized from the mouse and pen. Those events arrive with a `null` `device`.
133
80
 
134
81
  Joysticks and gamepads:
135
82
 
136
- - Gamepad `axisMotion` and `buttonDown`/`buttonUp` events for an axis or button SDL doesn't define are now dropped, instead of arriving with `axis: null` or `button: null` and adding a `null` key to `gamepadInstance.axes` or `gamepadInstance.buttons`.
137
- - Each joystick instance of a device now receives its own copy of `ballMotion` events. Instances used to share one event object whose `x`/`y` were overwritten for each instance in turn, so a listener that kept the event or read it later saw another instance's ball position.
138
- - Unplugging a device no longer mis-identifies the remaining ones. The device lists used to be rebuilt by matching devices on list position (or on name for audio), so removing a non-last joystick, gamepad, display, or audio device made cached device objects silently morph into other devices and made `deviceRemove`/`displayRemove` events report the wrong device. Every device list is now maintained from SDL's per-device hot-plug events, keyed by the device's stable id. As a side effect, `sdl.audio.devices` is no longer sorted by name — devices now stay in SDL's enumeration order, like every other device list.
139
- - `openDevice()` no longer risks opening the wrong physical device when another device's unplugging hasn't been processed yet. Devices are now opened by their stable id, which SDL never reuses, and pending device events are flushed (or, for sensors, the device list refetched) before the device is validated and opened.
140
- - Closing a joystick or gamepad instance from an event listener no longer crashes the process when more events for that instance are still in the queue.
141
- - Gamepad trigger axes now correctly report `0` when released instead of `0.5`, and inverted or half-axis mappings are no longer mis-scaled.
142
- - Trackball state and `ballMotion` events now report accumulated positions as documented, instead of the latest relative motion. Positions start at `0` when the instance is opened, instead of at whatever relative motion SDL happened to have accumulated since its last poll.
143
- - `sdl.joystick.devices` and `sdl.gamepad.devices` now return a copy of the device list, like `sdl.video.displays`, so modifying it no longer corrupts the library's internal state.
144
- - `rumble(0, 0)` and `rumbleTriggers(0, 0)` no longer schedule a keep-alive timer, so they no longer delay process exit while nothing is rumbling. `stopRumble()` and `stopRumbleTriggers()` are now truly equivalent to them, as documented.
145
- - Gamepad instances now receive `powerUpdate` events even when the device is not also open as a joystick.
146
- - The `steamHandleUpdate` event is now emitted correctly instead of a spurious `remap` event.
147
- - The `power` and `steamHandle` getters now poll for pending events first, like the other instance getters, instead of returning stale values.
148
- - `rumbleTriggers()` no longer stops the main rumble motors when its duration elapses, and pending rumble timeouts are cleared on close.
149
- - Rumble effects are now tracked per device instead of per instance, since all instances of a device share its motors. Stopping or replacing an effect from one instance no longer leaves another instance's timer keeping the process alive for up to 65 seconds, and closing an instance stops the device's rumble only once no other joystick or gamepad instance of it remains open.
150
- - A joystick or gamepad disconnecting mid-rumble no longer crashes the process when the rumble auto-stop timer fires.
151
- - Rumble durations above `65535` ms, the maximum SDL supports, now rumble for the full duration. They used to be silently cut short by SDL while the process was still kept alive for the full requested time.
152
- - Rumble and LED intensities are now rounded to the nearest hardware step instead of truncated, so values just below a step (such as `0.9999`) no longer land one step low.
153
- - `sdl.gamepad.addMappings()` now refreshes the device lists even when one of the mappings is invalid, so the devices made available by the mappings before it are reported.
154
- - `sdl.gamepad.addMappings()` now throws the error for an invalid mapping even if refreshing the device lists afterwards also fails, instead of replacing it with the unrelated refresh error.
155
- - `sdl.gamepad.addMappings()` now also refreshes the objects in `sdl.joystick.devices`. A joystick that a new mapping turns into a gamepad used to keep reporting its old `type` (such as `null`) instead of `'gamepad'`.
156
- - The `mapping`, `name`, and `type` of a gamepad's device object are now up to date when its `remap` event fires. `sdl.gamepad.addMappings()` used to emit the event before refreshing them, and remaps that SDL applied on its own did not refresh them at all.
157
- - `joystickInstance.setPlayer()`/`resetPlayer()` (and the gamepad equivalents) now update `player` on the device's objects in both `sdl.joystick.devices` and `sdl.gamepad.devices`, and throw if SDL refuses the assignment.
158
- - `setPlayer()` now also updates `player` on the device that previously held the requested index, which SDL moves to a free slot. It used to keep reporting its old index, so two devices reported the same player.
159
- - `rumble()` and `rumbleTriggers()` no longer keep the process alive for an effect SDL never started when the intensities round to zero.
160
- - `hasLed`, `hasRumble`, and `hasRumbleTriggers` on joystick and gamepad instances now report the device's current capabilities instead of the ones it had when opened, which SDL can change later (for example when it switches a PlayStation controller into enhanced mode). `setLed()`, `rumble()`, `stopRumble()`, `rumbleTriggers()`, and `stopRumbleTriggers()` now consistently throw when the device lacks the corresponding hardware; the stop calls and zero-intensity calls used to succeed silently.
161
-
162
- Instances (joystick, gamepad, sensor, and audio):
163
-
164
- - Reading state from a closed instance — including on the very read that discovers the device's removal — now throws "instance is closed" for every member (`axes`, `balls`, `buttons`, `hats`, `power`, `steamHandle`, sensor `data`), instead of returning stale state or, for sensors, a raw native error.
165
- - Closing is now robust against listeners: `closed` reports `true` while the `close` event is being emitted (so a listener that calls `close()` again no longer recurses forever), teardown completes before `close` is emitted (so a throwing listener no longer strands a closed-but-still-registered instance that leaks its handle and crashes the exit-time cleanup), and a device removal closes all of the device's instances and updates the device lists even when a listener throws.
166
- - The `close` event now passes the documented `{ type: 'close' }` event object.
167
- - Sensor instances left open on exit are now closed (and emit `close`) like all other instance types.
168
- - SDL is now shut down on exit even if a `close` listener throws during the exit-time cleanup.
83
+ - Unplugging a device no longer makes the remaining joystick, gamepad, display, or audio devices report the wrong identity, and `deviceRemove`/`displayRemove` report the right device.
84
+ - `openDevice()` no longer risks opening the wrong physical device while another device is being unplugged.
85
+ - Closing an instance from an event listener no longer crashes the process.
86
+ - Removed the axis scaling to their initial value.
87
+ - Trackball state and `ballMotion` events report accumulated positions.
88
+ - Rumble takes into account that the motors are owned by the device and may be shared across instances.
89
+ - `hasLed`, `hasRumble`, and `hasRumbleTriggers` report the device's current capabilities, and `setLed()`, `rumble()`, `stopRumble()`, `rumbleTriggers()`, and `stopRumbleTriggers()` consistently throw when the device lacks the hardware.
90
+ - `sdl.gamepad.addMappings()` refreshes the device lists (including `sdl.joystick.devices`) even when a mapping is invalid, and throws the error for the invalid mapping. The `mapping`, `name`, and `type` of a device are up to date when its `remap` event fires.
91
+ - `setPlayer()` and `resetPlayer()` update `player` on all of the device's objects, including the device that previously held the requested index, and throw if SDL refuses the assignment.
92
+ - The `power` and `steamHandle` getters, and sensor `data`, return current values instead of stale ones.
169
93
 
170
94
  Sensors:
171
95
 
172
- - `sdl.sensor.devices` no longer crashes when a sensor disappears while the list is being read (its `name` is `null`), no longer throws for sensors of unknown type (their `type` is `null`), and its device objects now remain valid across reads. `sdl.sensor.openDevice()` no longer throws a `TypeError`.
173
- - `sdl.sensor.devices` now reports `side` for left/right sensors (such as Joy-Con pairs) instead of always `null`.
174
- - Reading a sensor instance's `data` now pumps events first, so it returns current readings instead of values up to a second old.
175
- - `sdl.sensor.devices` returns a copy of the internal list, like the joystick and gamepad lists, so modifying it no longer corrupts the library's state.
96
+ - `sdl.sensor.devices` no longer crashes when a sensor disappears while the list is read or throws for sensors of unknown type, and reports `side` for left/right sensors (such as Joy-Con pairs).
97
+ - `sdl.sensor.openDevice()` no longer throws a `TypeError`.
176
98
 
177
99
  Audio:
178
100
 
179
- - Audio devices now report their sample format with an explicit byte order (such as `'s16le'`) instead of the native-byte-order alias (`'s16'`). The aliases share SDL's enum values with the explicit formats and were overwriting them in the lookup table.
180
- - The keep-alive timer that lets queued audio finish playing before the process exits now computes the device buffer's duration correctly, at the device's own sample rate rather than the stream's. A stream opened at a higher rate than its device could exit before the end of its audio had played.
181
- - The keep-alive timer for queued audio no longer overflows when the queue holds more than about 24.8 days of audio, which used to make the process spin on a 1 ms timer.
182
- - Closing or pausing a playback stream while Node.js is waiting for its queued audio to drain no longer keeps the process alive for the full queued duration.
183
- - The exit-time check for queued audio no longer throws when the device of a playing stream was unplugged just before the process would exit.
184
- - `putData()` and `getData()` now accept empty buffers as no-ops, as the docs already implied, instead of throwing "invalid bytes" on the zero-length chunks streaming pipelines naturally produce. A zero-length `Buffer` with no backing memory (such as `Buffer.alloc(0)`) is also accepted; SDL used to reject its null pointer.
185
- - `buffered` values larger than `32768` are now rejected instead of silently truncating to a driver-chosen buffer size.
101
+ - `putData()` and `getData()` accept empty buffers as no-ops, and reject a `bytes` count that isn't a whole number of sample frames with a validation error.
102
+ - `buffered` values larger than `32768` are rejected instead of silently truncated, and the buffer size the driver actually uses is reported on the stream's device.
186
103
  - `playbackStream.queued` no longer reports negative values for queues over 2 GiB.
187
- - `putData()` now rejects a `bytes` count that isn't a whole number of sample frames with a validation error, instead of a raw native error from SDL.
188
- - A `close` listener that throws no longer leaves a playback stream's keep-alive timer running after the stream is closed.
189
- - `stream.playing` is now `false` once the stream is closed, including when it is closed because its device was removed.
190
- - `readSample()` and `writeSample()` now reject non-`Buffer` arguments with a validation error instead of silently operating on array-likes.
191
- - `zeroSampleValue` for `u8` now matches SDL's silence value (`128`) instead of being one below it.
192
- - Plugging or unplugging an audio device no longer fires spurious `deviceAdd`/`deviceRemove` events for unrelated devices.
193
- - Unplugging an audio device now closes every stream opened from it, as documented, instead of only the first one SDL reports, and the device list is updated even when a `close` listener throws.
194
- - An audio device disappearing while the device list is being enumerated no longer crashes the process. The audio backend's own notification thread can remove a device mid-enumeration; the resulting error used to escape the internal polling loop as an uncaught exception. Devices that vanish mid-query are now skipped, like displays already were.
195
- - The buffer size the driver actually uses is now reported, as `buffered` on the stream's device. SDL only sizes the buffer when it first opens a device, so the `buffered` option is ignored for a device that is already open, and the keep-alive timing used to be computed from the wrong value.
196
- - Audio device objects no longer carry a `type` property, as the docs and types already said.
197
-
198
- Clipboard:
199
-
200
- - `sdl.clipboard.text` no longer throws when another application empties the clipboard mid-read, and no longer leaks the SDL-side copy of the text if creating the JS string fails (e.g. clipboard content beyond the JS string size limit).
201
-
202
- Validation and errors:
203
-
204
- - Passing a non-object (including `null`) as `options` to `createWindow()` or the audio `openDevice()` functions, or calling `putData()`/`getData()` without a buffer, now fails with the intended validation error instead of a raw `TypeError`. A non-object `options` used to be silently ignored by `createWindow()`.
205
- - Passing names of inherited `Object` members (such as `'constructor'` or `'toString'`) as keys, pixel formats, audio formats, cursors, or other enum values now fails validation with the intended error instead of leaking through to the native layer or, in the audio format helpers (on both `sdl.audio` and `@kmamal/sdl/helpers`), silently returning `undefined` or failing with a raw `TypeError`.
206
- - Integer arguments are now validated to fit in 32 bits everywhere the native layer reads them as such (window positions and sizes, image dimensions and strides, player indices, audio frequency, `numBytes`), and rumble durations are validated to fit the range of Node.js timers. Larger values used to silently wrap — `setSize(2 ** 32 + 100, 100)` set width 100, `rumble` durations above 2³¹−1 broke the auto-stop timer, and `setPlayer(2 ** 31)` silently behaved like `resetPlayer()`.
207
- - Enum values this build of the library doesn't know (a joystick or gamepad type, sensor type, power state, display orientation, display pixel format, touch device type, hat position, or gamepad axis or button name introduced by a newer runtime SDL) are now reported as `null` instead of an empty string.
208
- - SDL errors are now detected reliably, through SDL3's boolean return values or, where a call has none, the error message contents, instead of comparing `SDL_GetError()` pointers, which silently missed all errors when linked against an SDL build that returns a single static buffer. Stale SDL errors no longer cause spurious throws (and lost data) in `dequeue()`, `resize` events, and joystick/gamepad opening, and window methods called on a destroyed window now fail with a clear "invalid window id" error instead of appending whatever stale error text an earlier unrelated call had left behind.
209
- - `sdl.video.minBufferSize()` now validates `stride` and `height` instead of returning `NaN`.
210
- - The pixel-format and sample-format helpers (on `sdl.video`, `sdl.audio`, and `@kmamal/sdl/helpers`) now reject a non-string `format` with a validation error, instead of coercing values such as `['rgb24']` to a format name.
211
- - Values SDL can't determine (a joystick without a device path, such as a virtual joystick; a display, touch device, or sensor that vanishes while being queried; an unknown power state or key name) no longer leave SDL's error pending. It used to be picked up by later calls, which reported it as a spurious "SDL silent error" when opening a joystick or gamepad or adding gamepad mappings.
212
- - Reading `sdl.clipboard.text` without a video subsystem and a failing `sdl.mouse.resetCursor()` no longer leave SDL's error pending, and `resetCursor()` now reports SDL's actual error message.
213
- - `hasLed`, `hasRumble`, and `hasRumbleTriggers` now throw when SDL fails to query the device's capabilities, instead of reporting `false`.
214
-
215
- Native resource handling:
216
-
217
- - Fixed a use-after-free when destroying a window.
218
- - Fixed native leaks: opening the same joystick, gamepad, or sensor multiple times, a failure while opening a joystick or gamepad, a failure while creating a window (such as renderer creation failing), a failure to create the JS counterpart of a gamepad mapping string during device enumeration, `mouse.setCursor()`, and file drop events all used to leak the corresponding SDL resource.
219
- - `window.render()` no longer leaks a texture on every call if SDL fails to cache it on the window.
220
- - `window.setAccelerated()` and `window.setVsync()` no longer throw after successfully switching the renderer when SDL fails to report its name or vsync state, which used to leave `accelerated` and `vsync` reporting the old renderer's values.
221
- - Windows recreate their renderer when SDL reports that the graphics device was lost (for example after a GPU driver reset). `window.render()` used to fail from then on.
222
- - SDL event types the library doesn't handle (such as gamepad touchpad events) no longer make a wasted native-to-JS call per event.
223
-
224
- Docs, types, and loading:
225
-
226
- - The migration guide no longer claims that rumble durations above `65535` ms throw. It now describes the actual change to `rumble()` and `rumbleTriggers()`: `duration` defaults to `null`, and `0` is rejected.
227
- - Many fixes to the TypeScript declarations to match the implementation. Every event-emitting object is now declared as an `EventEmitter` (so `once()`, `off()`, `removeAllListeners()`, e.t.c. type-check), the `'error'` event is declared, the `sdl.video` pixel-format helpers and the new mouse members are included, and the whole `@kmamal/sdl/helpers` sub-module is covered instead of only its `audio` part.
228
- - The virtual key `'clear/again'` is now included in the API reference's virtual-key list. It was the only key value the mapping could produce that the docs omitted.
229
- - `window.native.subsystem` is now `null` on Windows and macOS instead of absent, and is no longer optional in the types.
230
- - Type fixes: `createWindow()`'s `x` and `y` options accept `null`, and the `orientation` on `displayOrient` events is nullable, both matching the implementation and docs.
231
- - The docs now state the constraints the API enforces on rumble `duration`, audio `frequency`, the `bytes` argument of `putData()`/`getData()`, and window positions and sizes.
232
- - The docs now also state the 32-bit limits on player indices, audio `frequency`, and the `bytes` argument of `putData()`/`getData()`, the limits on image `width`, `height`, and `stride`, and the allowed range of the cursor hotspot.
233
- - The docs now give the correct range for gamepad trigger axes, `0` to `1`, instead of `-1` to `+1`, and state the range of the `value` on `axisMotion` events.
234
- - The docs no longer describe the `'close'` event of windows, instances, and streams as firing before the object is destroyed or closed. It fires afterwards, once the object already reports `destroyed`/`closed`.
235
- - The `readSample()`/`writeSample()` docs no longer claim that `'f32'` is equivalent to `readFloatLE()`/`writeFloatLE()`. `'f32'` is in native byte order, so that only holds on little-endian machines.
236
- - Type fixes: the `dstRect` option of `window.render()` accepts `null`, matching the implementation and docs.
237
- - The docs now state that the `dstRect` of `window.render()` is in pixels, that `bytesPerPixel()` is `2` for `'p010'`, and no longer describe recording devices and streams in terms of playback.
238
- - The docs no longer claim that `vsync` requires `accelerated`. SDL3 supports vsync with the software renderer too.
239
- - The docs now say that `createWindow()` defaults to the primary display, which isn't necessarily `sdl.video.displays[0]`, and the types accept `null` for its `display`, `width`, and `height` options.
104
+ - `stream.playing` is `false` once the stream is closed.
105
+ - `readSample()` and `writeSample()` reject non-`Buffer` arguments, and `zeroSampleValue` for `u8` is `128`.
106
+ - Unplugging an audio device closes every stream opened from it, and plugging or unplugging one no longer fires spurious events for unrelated devices or crashes the process.
107
+
108
+ Other:
109
+
110
+ - Fixed native memory leaks when opening devices, creating windows, setting cursors, and handling file drops.
111
+ - Listening for `newListener` or `removeListener` no longer keeps the process alive forever.
112
+ - `emit()` now returns whether the event had listeners, as `EventEmitter` specifies.
113
+ - `sdl.clipboard.text` no longer throws when another application empties the clipboard mid-read.
114
+ - Integer arguments that cross into native code are validated to fit in 32 bits instead of silently wrapping.
115
+ - Enum values this build doesn't know are reported as `null` instead of an empty string.
116
+ - SDL errors are detected reliably, and stale SDL errors no longer cause spurious "SDL silent error" throws or lost data.
240
117
  - The library no longer fails to load on systems where the audio or video subsystem can't be initialized, such as headless servers.
241
- - The `sdl.info` sample in the API reference now shows SDL3 data instead of SDL2's.
242
- - The docs now give the gamepad device `type` as `<GamepadType>`, like the TS declarations.
243
- - `Window`, `JoystickInstance`, `GamepadInstance`, `SensorInstance`, and the `AudioStream` classes are now declared as interfaces instead of classes. The types used to declare a runtime `Sdl` export with constructible classes, so code like `x instanceof Sdl.Video.Window` compiled but crashed, since the library exports no such value and the classes can't be constructed directly.
244
- - Joystick hat positions (`joystickInstance.hats` and the `value` of `hatMotion` events) are now documented and typed as nullable, matching the implementation, which reports `null` for positions SDL doesn't define.
245
- - The docs and types now use the same parameter names as the implementation and its error messages: `lowFreqRumble`/`highFreqRumble` for `rumble()`, `leftRumble`/`rightRumble` for `rumbleTriggers()`, and `player` for `setPlayer()`.
246
- - The docs now state that `sdl.mouse.setPosition()` accepts fractional coordinates and that `createWindow()` accepts `null` for `width` and `height`.
247
-
248
- Building from source:
249
-
250
- - The native addon now compiles on FreeBSD, OpenBSD, and NetBSD, whose X11 and Wayland windowing is the same as on Linux. The platform checks in `window.cpp` and `binding.gyp` only matched Linux, so builds on the BSDs failed.
251
- - Building SDL from source (the fallback when no prebuilt SDL is available) no longer drops SDL's license from `dist/`, and a missing license now fails the build instead of being silently skipped.
252
- - Building SDL from source no longer crashes on Windows.
253
- - The native addon now compiles on Windows under SDL3, which no longer pulls in the declarations of `HWND` and `HINSTANCE`.
254
- - The native addon is now compiled with warnings enabled and treated as errors on macOS and Windows too, not only on Linux, and the `_THREAD_SAFE`/`_REENTRANT` defines now actually apply there.
255
- - `NO_PARALLEL=0` and `NO_PARALLEL=false` no longer disable the parallel native build, matching how the other environment variables are read.
256
118
 
257
119
  ## [v0.11.13] - 2025-08-30
258
120
 
@@ -303,7 +165,8 @@ Building from source:
303
165
 
304
166
  - Started keeping this changelog.
305
167
 
306
- [unreleased]: https://github.com/kmamal/node-sdl/compare/v0.11.13...HEAD
168
+ [unreleased]: https://github.com/kmamal/node-sdl/compare/v1.0.0...HEAD
169
+ [v1.0.0]: https://github.com/kmamal/node-sdl/compare/v0.11.13...v1.0.0
307
170
  [v0.11.13]: https://github.com/kmamal/node-sdl/compare/v0.11.12...v0.11.13
308
171
  [v0.11.12]: https://github.com/kmamal/node-sdl/compare/v0.11.11...v0.11.12
309
172
  [v0.11.11]: https://github.com/kmamal/node-sdl/compare/v0.11.10...v0.11.11
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
6
 
7
7
  > [!NOTE]
8
- > This version migrated from SDL2 to SDL3.
8
+ > Version 1.0.0 has migrated from SDL2 to SDL3.
9
9
  > Most of the API is unchanged, but several changes break compatibility.
10
10
  > The [migration guide](https://github.com/kmamal/node-sdl/tree/master/docs/migrating-to-sdl3.md) lists them all.
11
11
 
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.0.0-2",
2
+ "version": "1.0.0-3",
3
3
  "name": "@kmamal/sdl",
4
4
  "description": "SDL bindings for Node.js",
5
5
  "keywords": [
@@ -69,9 +69,9 @@
69
69
  "devDependencies": {
70
70
  "@kmamal/evdev": "0.0.8",
71
71
  "@kmamal/testing": "0.0.34",
72
- "@types/node": "26.3.0",
72
+ "@types/node": "26.6.4",
73
73
  "node-addon-api": "8.9.2",
74
- "node-gyp": "13.0.2"
74
+ "node-gyp": "13.1.0"
75
75
  },
76
76
  "config": {
77
77
  "sdl": {
@@ -84,6 +84,6 @@
84
84
  "@kmamal/evdev": true
85
85
  },
86
86
  "dependencies": {
87
- "modern-tar": "0.8.4"
87
+ "modern-tar": "0.8.5"
88
88
  }
89
89
  }
@@ -37,15 +37,16 @@ class AudioStream extends EventsViaPoll {
37
37
 
38
38
  this._id = id
39
39
  this._recording = recording
40
+ const helper = AudioFormatHelpers[format]
41
+
40
42
  this._device = device
41
43
  this._channels = channels
42
- this._format = format
44
+ this._format = helper.name
43
45
  this._frequency = frequency
44
46
 
45
47
  this._playing = false
46
48
  this._closed = false
47
49
 
48
- const helper = AudioFormatHelpers[this._format]
49
50
  this._bytesPerSample = helper.bytesPerSample
50
51
  this._minSampleValue = helper.minSampleValue
51
52
  this._maxSampleValue = helper.maxSampleValue
@@ -118,8 +119,10 @@ class AudioStream extends EventsViaPoll {
118
119
  // We might be inside an event listener
119
120
  this._retire(() => Object.assign(new Error("stream is closed"), { id: this._id }))
120
121
 
121
- try { this.emit('close', { type: 'close' }) }
122
- catch (error) { this.emit('error', error) }
122
+ Globals.events.withoutPolling(() => {
123
+ try { this.emit('close', { type: 'close' }) }
124
+ catch (error) { this.emit('error', error) }
125
+ })
123
126
  }
124
127
  }
125
128
 
@@ -64,6 +64,10 @@ const AudioFormatHelpers = Object.assign(Object.create(null), {
64
64
  },
65
65
  })
66
66
 
67
+ for (const [ key, value ] of Object.entries(AudioFormatHelpers)) {
68
+ value.name = key
69
+ }
70
+
67
71
  if (Os.endianness() === 'LE') {
68
72
  AudioFormatHelpers.s16 = AudioFormatHelpers.s16le
69
73
  AudioFormatHelpers.s32 = AudioFormatHelpers.s32le
@@ -489,6 +489,12 @@ const poll = () => {
489
489
  finally { polling = false }
490
490
  }
491
491
 
492
+ const withoutPolling = (fn) => {
493
+ const prevValue = polling
494
+ try { fn() }
495
+ finally { polling = prevValue }
496
+ }
497
+
492
498
  let pollInterval = null
493
499
 
494
500
  const switchToPollingFast = () => {
@@ -509,6 +515,7 @@ const stopPolling = () => {
509
515
 
510
516
  Globals.events = {
511
517
  poll,
518
+ withoutPolling,
512
519
  switchToPollingFast,
513
520
  switchToPollingSlow,
514
521
  stopPolling,
@@ -133,7 +133,7 @@ class GamepadInstance extends EventsViaPoll {
133
133
  if (highFreqRumble < 0 || highFreqRumble > 1) { throw Object.assign(new Error("highFreqRumble must be between 0 and 1"), { highFreqRumble }) }
134
134
  if (duration !== null) {
135
135
  if (!Number.isInteger(duration)) { throw Object.assign(new Error("duration must be an integer"), { duration }) }
136
- if (duration < 1 || duration > 2 ** 31 - 1) { throw Object.assign(new Error("duration must be a positive 32-bit integer"), { duration }) }
136
+ if (duration < 0 || duration > 2 ** 31 - 1) { throw Object.assign(new Error("duration must be a non-negative 32-bit integer"), { duration }) }
137
137
  }
138
138
 
139
139
  if (!this.hasRumble) { throw Object.assign(new Error("device has no rumble"), { id: this._device.id }) }
@@ -164,7 +164,7 @@ class GamepadInstance extends EventsViaPoll {
164
164
  if (rightRumble < 0 || rightRumble > 1) { throw Object.assign(new Error("rightRumble must be between 0 and 1"), { rightRumble }) }
165
165
  if (duration !== null) {
166
166
  if (!Number.isInteger(duration)) { throw Object.assign(new Error("duration must be an integer"), { duration }) }
167
- if (duration < 1 || duration > 2 ** 31 - 1) { throw Object.assign(new Error("duration must be a positive 32-bit integer"), { duration }) }
167
+ if (duration < 0 || duration > 2 ** 31 - 1) { throw Object.assign(new Error("duration must be a non-negative 32-bit integer"), { duration }) }
168
168
  }
169
169
 
170
170
  if (!this.hasRumbleTriggers) { throw Object.assign(new Error("device has no trigger rumble"), { id: this._device.id }) }
@@ -201,8 +201,10 @@ class GamepadInstance extends EventsViaPoll {
201
201
  // We might be inside an event listener
202
202
  this._retire(() => Object.assign(new Error("instance is closed"), { id: this._device.id }))
203
203
 
204
- try { this.emit('close', { type: 'close' }) }
205
- catch (error) { this.emit('error', error) }
204
+ Globals.events.withoutPolling(() => {
205
+ try { this.emit('close', { type: 'close' }) }
206
+ catch (error) { this.emit('error', error) }
207
+ })
206
208
  }
207
209
  }
208
210
 
@@ -8,6 +8,13 @@ module.exports = {
8
8
  isYuv (format) { return getVideoFormatHelpers(format).isYuv },
9
9
  isPlanarYuv (format) { return getVideoFormatHelpers(format).isPlanarYuv },
10
10
 
11
+ minStride (format, width) {
12
+ const helpers = getVideoFormatHelpers(format)
13
+ if (!Number.isInteger(width)) { throw Object.assign(new Error("width must be an integer"), { width }) }
14
+ if (width < 0) { throw Object.assign(new Error("width must be non-negative"), { width }) }
15
+ return helpers.minStride(width)
16
+ },
17
+
11
18
  minBufferSize (format, stride, height) {
12
19
  const helpers = getVideoFormatHelpers(format)
13
20
  if (!Number.isInteger(stride)) { throw Object.assign(new Error("stride must be an integer"), { stride }) }
@@ -133,7 +133,7 @@ class JoystickInstance extends EventsViaPoll {
133
133
  if (highFreqRumble < 0 || highFreqRumble > 1) { throw Object.assign(new Error("highFreqRumble must be between 0 and 1"), { highFreqRumble }) }
134
134
  if (duration !== null) {
135
135
  if (!Number.isInteger(duration)) { throw Object.assign(new Error("duration must be an integer"), { duration }) }
136
- if (duration < 1 || duration > 2 ** 31 - 1) { throw Object.assign(new Error("duration must be a positive 32-bit integer"), { duration }) }
136
+ if (duration < 0 || duration > 2 ** 31 - 1) { throw Object.assign(new Error("duration must be a non-negative 32-bit integer"), { duration }) }
137
137
  }
138
138
 
139
139
  if (!this.hasRumble) { throw Object.assign(new Error("device has no rumble"), { id: this._device.id }) }
@@ -164,7 +164,7 @@ class JoystickInstance extends EventsViaPoll {
164
164
  if (rightRumble < 0 || rightRumble > 1) { throw Object.assign(new Error("rightRumble must be between 0 and 1"), { rightRumble }) }
165
165
  if (duration !== null) {
166
166
  if (!Number.isInteger(duration)) { throw Object.assign(new Error("duration must be an integer"), { duration }) }
167
- if (duration < 1 || duration > 2 ** 31 - 1) { throw Object.assign(new Error("duration must be a positive 32-bit integer"), { duration }) }
167
+ if (duration < 0 || duration > 2 ** 31 - 1) { throw Object.assign(new Error("duration must be a non-negative 32-bit integer"), { duration }) }
168
168
  }
169
169
 
170
170
  if (!this.hasRumbleTriggers) { throw Object.assign(new Error("device has no trigger rumble"), { id: this._device.id }) }
@@ -199,8 +199,10 @@ class JoystickInstance extends EventsViaPoll {
199
199
  // We might be inside an event listener
200
200
  this._retire(() => Object.assign(new Error("instance is closed"), { id: this._device.id }))
201
201
 
202
- try { this.emit('close', { type: 'close' }) }
203
- catch (error) { this.emit('error', error) }
202
+ Globals.events.withoutPolling(() => {
203
+ try { this.emit('close', { type: 'close' }) }
204
+ catch (error) { this.emit('error', error) }
205
+ })
204
206
  }
205
207
  }
206
208
 
@@ -20,6 +20,8 @@ const clearEffectTimeout = (effect, id) => {
20
20
  const MAX_DURATION = 0xFFFF
21
21
 
22
22
  const startEffect = (kind, id, a, b, duration) => {
23
+ if (duration === 0) { return stopEffect(kind, id) }
24
+
23
25
  const effect = effects[kind]
24
26
  a = Math.round(a * 0xFFFF)
25
27
  b = Math.round(b * 0xFFFF)
@@ -59,8 +59,10 @@ class SensorInstance extends EventsViaPoll {
59
59
  // We might be inside an event listener
60
60
  this._retire(() => Object.assign(new Error("instance is closed"), { id: this._device.id }))
61
61
 
62
- try { this.emit('close', { type: 'close' }) }
63
- catch (error) { this.emit('error', error) }
62
+ Globals.events.withoutPolling(() => {
63
+ try { this.emit('close', { type: 'close' }) }
64
+ catch (error) { this.emit('error', error) }
65
+ })
64
66
  }
65
67
  }
66
68
 
@@ -1,3 +1,4 @@
1
+ const Os = require('node:os')
1
2
 
2
3
  const minStride = (bytesPerPixel) => (width) => width * bytesPerPixel
3
4
  const minStridePacked = (width) => 4 * Math.ceil(width / 2)
@@ -9,18 +10,18 @@ const rgb = (bytesPerPixel) => ({
9
10
  bytesPerPixel,
10
11
  isYuv: false,
11
12
  isPlanarYuv: false,
12
- isRenderable: true,
13
13
  minStride: minStride(bytesPerPixel),
14
14
  minBufferSize,
15
+ isRenderable: true,
15
16
  })
16
17
 
17
18
  const yuv = (bytesPerPixel, isPlanarYuv, isRenderable = true) => ({
18
19
  bytesPerPixel,
19
20
  isYuv: true,
20
21
  isPlanarYuv,
21
- isRenderable,
22
22
  minStride: isPlanarYuv ? minStride(bytesPerPixel) : minStridePacked,
23
23
  minBufferSize: isPlanarYuv ? minBufferSizePlanar : minBufferSize,
24
+ isRenderable,
24
25
  })
25
26
 
26
27
  const VideoFormatHelpers = Object.assign(Object.create(null), {
@@ -71,14 +72,6 @@ const VideoFormatHelpers = Object.assign(Object.create(null), {
71
72
  argb128f: rgb(16),
72
73
  bgra128f: rgb(16),
73
74
  abgr128f: rgb(16),
74
- rgba32: rgb(4),
75
- argb32: rgb(4),
76
- bgra32: rgb(4),
77
- abgr32: rgb(4),
78
- rgbx32: rgb(4),
79
- xrgb32: rgb(4),
80
- bgrx32: rgb(4),
81
- xbgr32: rgb(4),
82
75
  yv12: yuv(1, true),
83
76
  iyuv: yuv(1, true),
84
77
  yuy2: yuv(2, false),
@@ -89,6 +82,31 @@ const VideoFormatHelpers = Object.assign(Object.create(null), {
89
82
  p010: { ...yuv(2, true, false), minStride: minStridePacked },
90
83
  })
91
84
 
85
+ for (const [ key, value ] of Object.entries(VideoFormatHelpers)) {
86
+ value.name = key
87
+ }
88
+
89
+ if (Os.endianness() === 'LE') {
90
+ VideoFormatHelpers.rgba32 = VideoFormatHelpers.abgr8888
91
+ VideoFormatHelpers.argb32 = VideoFormatHelpers.bgra8888
92
+ VideoFormatHelpers.bgra32 = VideoFormatHelpers.argb8888
93
+ VideoFormatHelpers.abgr32 = VideoFormatHelpers.rgba8888
94
+ VideoFormatHelpers.rgbx32 = VideoFormatHelpers.xbgr8888
95
+ VideoFormatHelpers.xrgb32 = VideoFormatHelpers.bgrx8888
96
+ VideoFormatHelpers.bgrx32 = VideoFormatHelpers.xrgb8888
97
+ VideoFormatHelpers.xbgr32 = VideoFormatHelpers.rgbx8888
98
+ }
99
+ else {
100
+ VideoFormatHelpers.rgba32 = VideoFormatHelpers.rgba8888
101
+ VideoFormatHelpers.argb32 = VideoFormatHelpers.argb8888
102
+ VideoFormatHelpers.bgra32 = VideoFormatHelpers.bgra8888
103
+ VideoFormatHelpers.abgr32 = VideoFormatHelpers.abgr8888
104
+ VideoFormatHelpers.rgbx32 = VideoFormatHelpers.rgbx8888
105
+ VideoFormatHelpers.xrgb32 = VideoFormatHelpers.xrgb8888
106
+ VideoFormatHelpers.bgrx32 = VideoFormatHelpers.bgrx8888
107
+ VideoFormatHelpers.xbgr32 = VideoFormatHelpers.xbgr8888
108
+ }
109
+
92
110
  const getFormatHelpers = (format) => {
93
111
  if (typeof format !== 'string') { throw Object.assign(new Error("format must be a string"), { format }) }
94
112
  const helpers = VideoFormatHelpers[format]
@@ -46,6 +46,13 @@ const video = new class extends EventsViaPoll {
46
46
  isYuv (format) { return getFormatHelpers(format).isYuv }
47
47
  isPlanarYuv (format) { return getFormatHelpers(format).isPlanarYuv }
48
48
 
49
+ minStride (format, width) {
50
+ const helpers = getFormatHelpers(format)
51
+ if (!Number.isInteger(width)) { throw Object.assign(new Error("width must be an integer"), { width }) }
52
+ if (width < 0) { throw Object.assign(new Error("width must be non-negative"), { width }) }
53
+ return helpers.minStride(width)
54
+ }
55
+
49
56
  minBufferSize (format, stride, height) {
50
57
  const helpers = getFormatHelpers(format)
51
58
  if (!Number.isInteger(stride)) { throw Object.assign(new Error("stride must be an integer"), { stride }) }
@@ -82,7 +82,10 @@ class Window extends EventsViaPoll {
82
82
  if (typeof borderless !== 'boolean') { throw Object.assign(new Error("borderless must be a boolean"), { borderless }) }
83
83
  if (typeof alwaysOnTop !== 'boolean') { throw Object.assign(new Error("alwaysOnTop must be a boolean"), { alwaysOnTop }) }
84
84
  if (hasAccelerated && typeof accelerated !== 'boolean') { throw Object.assign(new Error("accelerated must be a boolean"), { accelerated }) }
85
- if (hasVsync && typeof vsync !== 'boolean') { throw Object.assign(new Error("vsync must be a boolean"), { vsync }) }
85
+ if (hasVsync) {
86
+ if (!Number.isInteger(vsync)) { throw Object.assign(new Error("vsync must be an integer"), { vsync }) }
87
+ if (vsync < -1 || vsync > 2 ** 31 - 1) { throw Object.assign(new Error("vsync must be -1 or a non-negative 32-bit integer"), { vsync }) }
88
+ }
86
89
  if (typeof opengl !== 'boolean') { throw Object.assign(new Error("opengl must be a boolean"), { opengl }) }
87
90
  if (typeof webgpu !== 'boolean') { throw Object.assign(new Error("webgpu must be a boolean"), { webgpu }) }
88
91
  if (display !== null && (x !== null || y !== null)) { throw Object.assign(new Error("display and x/y are mutually exclusive"), { display, x, y }) }
@@ -111,7 +114,7 @@ class Window extends EventsViaPoll {
111
114
  borderless,
112
115
  alwaysOnTop,
113
116
  accelerated ?? true,
114
- vsync ?? true,
117
+ vsync ?? 1,
115
118
  opengl,
116
119
  webgpu,
117
120
  )
@@ -154,32 +157,34 @@ class Window extends EventsViaPoll {
154
157
  // Manually emit some initial events for convenience
155
158
  process.nextTick(() => {
156
159
  if (this._destroyed) { return }
157
- try {
158
- this.emit('move', {
159
- x: this._x,
160
- y: this._y,
161
- type: 'move',
162
- })
163
- }
164
- catch (error) { this.emit('error', error) }
165
- try {
166
- this.emit('resize', {
167
- width: this._width,
168
- height: this._height,
169
- pixelWidth: this._pixelWidth,
170
- pixelHeight: this._pixelHeight,
171
- type: 'resize',
172
- })
173
- }
174
- catch (error) { this.emit('error', error) }
175
- if (this._visible) {
160
+ Globals.events.withoutPolling(() => {
176
161
  try {
177
- this.emit('expose', {
178
- type: 'expose',
162
+ this.emit('move', {
163
+ x: this._x,
164
+ y: this._y,
165
+ type: 'move',
179
166
  })
180
167
  }
181
168
  catch (error) { this.emit('error', error) }
182
- }
169
+ try {
170
+ this.emit('resize', {
171
+ width: this._width,
172
+ height: this._height,
173
+ pixelWidth: this._pixelWidth,
174
+ pixelHeight: this._pixelHeight,
175
+ type: 'resize',
176
+ })
177
+ }
178
+ catch (error) { this.emit('error', error) }
179
+ if (this._visible) {
180
+ try {
181
+ this.emit('expose', {
182
+ type: 'expose',
183
+ })
184
+ }
185
+ catch (error) { this.emit('error', error) }
186
+ }
187
+ })
183
188
  })
184
189
  }
185
190
 
@@ -378,7 +383,8 @@ class Window extends EventsViaPoll {
378
383
  if (this._opengl) { throw new Error("can't call setVsync in opengl mode") }
379
384
  if (this._webgpu) { throw new Error("can't call setVsync in webgpu mode") }
380
385
 
381
- if (typeof vsync !== 'boolean') { throw Object.assign(new Error("vsync must be a boolean"), { vsync }) }
386
+ if (!Number.isInteger(vsync)) { throw Object.assign(new Error("vsync must be an integer"), { vsync }) }
387
+ if (vsync < -1 || vsync > 2 ** 31 - 1) { throw Object.assign(new Error("vsync must be -1 or a non-negative 32-bit integer"), { vsync }) }
382
388
 
383
389
  const result = Bindings.window_setAcceleratedAndVsync(this._id, this._accelerated, vsync)
384
390
  this._accelerated = result.accelerated
@@ -583,21 +589,25 @@ class Window extends EventsViaPoll {
583
589
  // We might be inside an event listener
584
590
  this._retire(() => Object.assign(new Error("window is destroyed"), { id: this._id }))
585
591
 
586
- try { this.emit('close', { type: 'close' }) }
587
- catch (error) { this.emit('error', error) }
592
+ Globals.events.withoutPolling(() => {
593
+ try { this.emit('close', { type: 'close' }) }
594
+ catch (error) { this.emit('error', error) }
595
+ })
588
596
  }
589
597
 
590
598
  destroyGently () {
591
599
  if (this._destroyed) { throw Object.assign(new Error("window is destroyed"), { id: this._id }) }
592
600
 
593
601
  let shouldPrevent = false
594
- try {
595
- this.emit('beforeClose', {
596
- type: 'beforeClose',
597
- prevent: () => { shouldPrevent = true },
598
- })
599
- }
600
- catch (error) { this.emit('error', error) }
602
+ Globals.events.withoutPolling(() => {
603
+ try {
604
+ this.emit('beforeClose', {
605
+ type: 'beforeClose',
606
+ prevent: () => { shouldPrevent = true },
607
+ })
608
+ }
609
+ catch (error) { this.emit('error', error) }
610
+ })
601
611
  if (shouldPrevent) { return }
602
612
 
603
613
  // A listener may have already destroyed the window
@@ -28,7 +28,7 @@ gamepad::getSteamHandle (Napi::Env &env, SDL_Gamepad *gamepad)
28
28
  {
29
29
  Uint64 _steam_handle = SDL_GetGamepadSteamHandle(gamepad);
30
30
  return _steam_handle != 0
31
- ? Napi::Buffer<Uint64>::Copy(env, &_steam_handle, 1)
31
+ ? Napi::BigInt::New(env, _steam_handle)
32
32
  : env.Null();
33
33
  }
34
34
 
@@ -58,7 +58,7 @@ updateRenderer(
58
58
  Napi::Env &env,
59
59
  SDL_Window *window,
60
60
  bool *is_accelerated,
61
- bool *is_vsync
61
+ int *vsync
62
62
  ) {
63
63
  int window_id = SDL_GetWindowID(window);
64
64
  // Not likely to fail.
@@ -82,20 +82,20 @@ updateRenderer(
82
82
 
83
83
  if (renderer == nullptr) {
84
84
  std::ostringstream message;
85
- message << "SDL_CreateRenderer(" << window_id << ", " << *is_accelerated << ", " << *is_vsync << ") error: " << SDL_GetError();
85
+ message << "SDL_CreateRenderer(" << window_id << ", " << *is_accelerated << ", " << *vsync << ") error: " << SDL_GetError();
86
86
  SDL_ClearError();
87
87
  throw Napi::Error::New(env, message.str());
88
88
  }
89
89
 
90
- if (!SDL_SetRenderVSync(renderer, *is_vsync ? 1 : 0)) { SDL_ClearError(); }
90
+ if (!SDL_SetRenderVSync(renderer, *vsync)) { SDL_ClearError(); }
91
91
 
92
92
  const char *renderer_name = SDL_GetRendererName(renderer);
93
93
  if (renderer_name == nullptr) { SDL_ClearError(); }
94
94
  else { *is_accelerated = SDL_strcmp(renderer_name, SDL_SOFTWARE_RENDERER) != 0; }
95
95
 
96
- int vsync;
97
- if (!SDL_GetRenderVSync(renderer, &vsync)) { SDL_ClearError(); }
98
- else { *is_vsync = vsync != 0; }
96
+ int actual_vsync;
97
+ if (!SDL_GetRenderVSync(renderer, &actual_vsync)) { SDL_ClearError(); }
98
+ else { *vsync = actual_vsync; }
99
99
  }
100
100
 
101
101
 
@@ -119,7 +119,7 @@ window::create (const Napi::CallbackInfo &info)
119
119
  bool is_webgpu = info[14].As<Napi::Boolean>().Value();
120
120
  bool has_renderer = !is_opengl && !is_webgpu;
121
121
  bool is_accelerated = has_renderer && info[11].As<Napi::Boolean>().Value();
122
- bool is_vsync = has_renderer && info[12].As<Napi::Boolean>().Value();
122
+ int vsync = has_renderer ? info[12].As<Napi::Number>().Int32Value() : 0;
123
123
 
124
124
  Uint64 desired_flags = 0
125
125
  | SDL_WINDOW_HIDDEN | SDL_WINDOW_HIGH_PIXEL_DENSITY
@@ -294,7 +294,7 @@ window::create (const Napi::CallbackInfo &info)
294
294
  native.Set("gpu", Napi::Buffer<GPU_NativeData>::Copy(env, &native_gpu, 1));
295
295
  }
296
296
  else {
297
- updateRenderer(env, window, &is_accelerated, &is_vsync);
297
+ updateRenderer(env, window, &is_accelerated, &vsync);
298
298
  }
299
299
 
300
300
  if (is_visible && !SDL_ShowWindow(window)) {
@@ -339,7 +339,7 @@ window::create (const Napi::CallbackInfo &info)
339
339
  result.Set("alwaysOnTop", is_always_on_top);
340
340
  if (has_renderer) {
341
341
  result.Set("accelerated", is_accelerated);
342
- result.Set("vsync", is_vsync);
342
+ result.Set("vsync", vsync);
343
343
  }
344
344
  else {
345
345
  result.Set("accelerated", env.Null());
@@ -538,15 +538,15 @@ window::setAcceleratedAndVsync (const Napi::CallbackInfo &info)
538
538
 
539
539
  int window_id = info[0].As<Napi::Number>().Int32Value();
540
540
  bool is_accelerated = info[1].As<Napi::Boolean>().Value();
541
- bool is_vsync = info[2].As<Napi::Boolean>().Value();
541
+ int vsync = info[2].As<Napi::Number>().Int32Value();
542
542
 
543
543
  SDL_Window *window = getWindow(env, window_id);
544
544
 
545
- updateRenderer(env, window, &is_accelerated, &is_vsync);
545
+ updateRenderer(env, window, &is_accelerated, &vsync);
546
546
 
547
547
  Napi::Object result = Napi::Object::New(env);
548
548
  result.Set("accelerated", is_accelerated);
549
- result.Set("vsync", is_vsync);
549
+ result.Set("vsync", vsync);
550
550
 
551
551
  return result;
552
552
  }
@@ -5,12 +5,13 @@ export namespace SdlHelpers {
5
5
 
6
6
  export namespace Video {
7
7
 
8
- export type Format = Sdl.Video.Format
8
+ export type Format = Sdl.Video.Format | Sdl.Video.FormatAlias
9
9
 
10
10
  interface Module {
11
11
  bytesPerPixel (format: Format): number
12
12
  isYuv (format: Format): boolean
13
13
  isPlanarYuv (format: Format): boolean
14
+ minStride (format: Format, width: number): number
14
15
  minBufferSize (format: Format, stride: number, height: number): number
15
16
  }
16
17
 
@@ -42,7 +43,7 @@ export namespace SdlHelpers {
42
43
 
43
44
  export namespace Audio {
44
45
 
45
- export type Format = Sdl.Audio.Format
46
+ export type Format = Sdl.Audio.Format | Sdl.Audio.FormatAlias
46
47
 
47
48
  interface Module {
48
49
  bytesPerSample (format: Format): number
@@ -294,7 +294,7 @@ export namespace Events {
294
294
 
295
295
  export interface SteamHandleUpdate extends GamepadEvent {
296
296
  readonly type: 'steamHandleUpdate'
297
- readonly steamHandle: Buffer | null
297
+ readonly steamHandle: bigint | null
298
298
  }
299
299
 
300
300
  export interface Remap extends GamepadEvent { readonly type: 'remap' }
@@ -505,14 +505,6 @@ export namespace Sdl {
505
505
  | 'argb128f'
506
506
  | 'bgra128f'
507
507
  | 'abgr128f'
508
- | 'rgba32'
509
- | 'argb32'
510
- | 'bgra32'
511
- | 'abgr32'
512
- | 'rgbx32'
513
- | 'xrgb32'
514
- | 'bgrx32'
515
- | 'xbgr32'
516
508
  | 'yv12'
517
509
  | 'iyuv'
518
510
  | 'yuy2'
@@ -522,6 +514,16 @@ export namespace Sdl {
522
514
  | 'nv21'
523
515
  | 'p010'
524
516
 
517
+ export type FormatAlias
518
+ = 'rgba32'
519
+ | 'argb32'
520
+ | 'bgra32'
521
+ | 'abgr32'
522
+ | 'rgbx32'
523
+ | 'xrgb32'
524
+ | 'bgrx32'
525
+ | 'xbgr32'
526
+
525
527
  export type Scaling
526
528
  = 'nearest'
527
529
  | 'linear'
@@ -618,14 +620,14 @@ export namespace Sdl {
618
620
  readonly accelerated: boolean | null
619
621
  setAccelerated (accelerated: boolean): void
620
622
 
621
- readonly vsync: boolean | null
622
- setVsync (vsync: boolean): void
623
+ readonly vsync: number | null
624
+ setVsync (vsync: number): void
623
625
 
624
626
  readonly opengl: boolean
625
627
  readonly webgpu: boolean
626
628
  readonly native: {
627
- handle: Buffer | null,
628
- subsystem: 'x11' | 'wayland' | null,
629
+ readonly handle: Buffer | null,
630
+ readonly subsystem: 'x11' | 'wayland' | null,
629
631
  }
630
632
 
631
633
  readonly maximized: boolean
@@ -646,7 +648,7 @@ export namespace Sdl {
646
648
  setRelativeMouseMode (relative?: boolean): void
647
649
  unsetRelativeMouseMode (): void
648
650
 
649
- render (width: number, height: number, stride: number, format: Format, buffer: Buffer, options?: {
651
+ render (width: number, height: number, stride: number, format: Format | FormatAlias, buffer: Buffer, options?: {
650
652
  scaling?: Scaling,
651
653
  dstRect?: {
652
654
  x: number,
@@ -656,7 +658,7 @@ export namespace Sdl {
656
658
  } | null
657
659
  }): void
658
660
 
659
- setIcon (width: number, height: number, stride: number, format: Format, buffer: Buffer): void
661
+ setIcon (width: number, height: number, stride: number, format: Format | FormatAlias, buffer: Buffer): void
660
662
 
661
663
  flash (untilFocused?: boolean): void
662
664
  stopFlashing (): void
@@ -696,15 +698,16 @@ export namespace Sdl {
696
698
  borderless?: boolean
697
699
  alwaysOnTop?: boolean
698
700
  accelerated?: boolean
699
- vsync?: boolean
701
+ vsync?: number
700
702
  opengl?: boolean
701
703
  webgpu?: boolean
702
704
  }): Window
703
705
 
704
- bytesPerPixel (format: Format): number
705
- isYuv (format: Format): boolean
706
- isPlanarYuv (format: Format): boolean
707
- minBufferSize (format: Format, stride: number, height: number): number
706
+ bytesPerPixel (format: Format | FormatAlias): number
707
+ isYuv (format: Format | FormatAlias): boolean
708
+ isPlanarYuv (format: Format | FormatAlias): boolean
709
+ minStride (format: Format | FormatAlias, width: number): number
710
+ minBufferSize (format: Format | FormatAlias, stride: number, height: number): number
708
711
  }
709
712
  }
710
713
 
@@ -1023,7 +1026,7 @@ export namespace Sdl {
1023
1026
 
1024
1027
  setCursor (cursor: Cursor): void
1025
1028
  resetCursor (): void
1026
- setCursorImage (width: number, height: number, stride: number, format: Video.Format, buffer: Buffer, x: number, y: number): void
1029
+ setCursorImage (width: number, height: number, stride: number, format: Video.Format | Video.FormatAlias, buffer: Buffer, x: number, y: number): void
1027
1030
 
1028
1031
  showCursor (show?: boolean): void
1029
1032
  hideCursor (): void
@@ -1242,7 +1245,7 @@ export namespace Sdl {
1242
1245
  readonly device: Device
1243
1246
  readonly firmwareVersion: number | null
1244
1247
  readonly serialNumber: string | null
1245
- readonly steamHandle: Buffer | null
1248
+ readonly steamHandle: bigint | null
1246
1249
 
1247
1250
  readonly axes: { readonly [axis in Axis]: number }
1248
1251
  readonly buttons: { readonly [button in Button]: boolean }
@@ -1342,12 +1345,14 @@ export namespace Sdl {
1342
1345
  | 'u8'
1343
1346
  | 's16le'
1344
1347
  | 's16be'
1345
- | 's16'
1346
1348
  | 's32le'
1347
1349
  | 's32be'
1348
- | 's32'
1349
1350
  | 'f32le'
1350
1351
  | 'f32be'
1352
+
1353
+ export type FormatAlias
1354
+ = 's16'
1355
+ | 's32'
1351
1356
  | 'f32'
1352
1357
 
1353
1358
  export interface Device {
@@ -1362,7 +1367,7 @@ export namespace Sdl {
1362
1367
  export interface StreamOptions {
1363
1368
  readonly channels?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8
1364
1369
  readonly frequency?: number
1365
- readonly format?: Format
1370
+ readonly format?: Format | FormatAlias
1366
1371
  readonly buffered?: number
1367
1372
  }
1368
1373
 
@@ -1420,12 +1425,12 @@ export namespace Sdl {
1420
1425
  readonly playback: DeviceModule<AudioPlaybackStream>
1421
1426
  readonly recording: DeviceModule<AudioRecordingStream>
1422
1427
 
1423
- bytesPerSample (format: Format): number
1424
- minSampleValue (format: Format): number
1425
- maxSampleValue (format: Format): number
1426
- zeroSampleValue (format: Format): number
1427
- readSample (format: Format, buffer: Buffer, offset?: number): number
1428
- writeSample (format: Format, buffer: Buffer, value: number, offset?: number): number
1428
+ bytesPerSample (format: Format | FormatAlias): number
1429
+ minSampleValue (format: Format | FormatAlias): number
1430
+ maxSampleValue (format: Format | FormatAlias): number
1431
+ zeroSampleValue (format: Format | FormatAlias): number
1432
+ readSample (format: Format | FormatAlias, buffer: Buffer, offset?: number): number
1433
+ writeSample (format: Format | FormatAlias, buffer: Buffer, value: number, offset?: number): number
1429
1434
  }
1430
1435
  }
1431
1436