@kmamal/sdl v0.11.7

@kmamal/sdl

SDL bindings for Node.js. Provides window management, input events (keyboard, mouse, joysticks, controllers, sensors), audio playback and recording, clipboard manipulation, and battery status.

It should work on Linux, Mac, and Windows. Prebuilt binaries are available for x64 architectures, arm-based Macs, and Raspberry Pi.

Canvas2D, WebGL, and WebGPU

One goal of this project is to allow using Canvas2D, WebGL, and WebGPU without a browser. You can use the @napi-rs/canvas package to render using the Canvas2D API. For WebGL you can use @kmamal/gl and for WebGPU you can use @kmamal/gpu. Both WebGL and WebGPU support rendering directly to the window (without any intermediate buffer copying). Canvas2D still uses an intermediate buffer, but that might change in the future.

Installation

SDL is bundled along with the binaries so a separate installation is not necessary. This package is self-contained. Just run:

npm install @kmamal/sdl

(But if things go wrong do look over here)

Examples

"Hello, World!"

import sdl from '@kmamal/sdl'

const window = sdl.video.createWindow({ title: "Hello, World!" })
window.on('*', console.log)

Canvas2D

import sdl from '@kmamal/sdl'
import { createCanvas } from '@napi-rs/canvas'

// Setup
const window = sdl.video.createWindow({ title: "Canvas2D" })
const { pixelWidth: width, pixelHeight: height } = window
const canvas = createCanvas(width, height)
const ctx = canvas.getContext('2d')

// Clear screen to red
ctx.fillStyle = 'red'
ctx.fillRect(0, 0, width, height)

// Render to window
const buffer = Buffer.from(ctx.getImageData(0, 0, width, height).data)
window.render(width, height, width * 4, 'rgba32', buffer)

WebGL

import sdl from '@kmamal/sdl'
import createContext from '@kmamal/gl'

// Setup
const window = sdl.video.createWindow({ title: "WebGL", opengl: true })
const { pixelWidth: width, pixelHeight: height, native } = window
const gl = createContext(width, height, { window: native })

// Clear screen to red
gl.clearColor(1, 0, 0, 1)
gl.clear(gl.COLOR_BUFFER_BIT)

// Render to window
gl.swap()

WebGPU

import sdl from '@kmamal/sdl'
import gpu from '@kmamal/gpu'

// Setup
const window = sdl.video.createWindow({ title: "WebGPU", webgpu: true })
const instance = gpu.create([])
const adapter = await instance.requestAdapter()
const device = await adapter.requestDevice()
const renderer = gpu.renderGPUDeviceToWindow({ device, window })

// Clear screen to red
const commandEncoder = device.createCommandEncoder()
const renderPass = commandEncoder.beginRenderPass({
  colorAttachments: [
    {
      view: renderer.getCurrentTextureView(),
      clearValue: { r: 1.0, g: 0.0, b: 0.0, a: 1.0 },
      loadOp: 'clear',
      storeOp: 'store',
    },
  ],
})
renderPass.end()
device.queue.submit([ commandEncoder.finish() ])

// Render to window
renderer.swap()

More examples

Check the examples/ folder.

API Reference

Contents

• sdl
  • sdl.info
• sdl.video
  • Image data
  • High-DPI
  • Pixel formats
  • Event: 'displayAdd'
  • Event: 'displayRemove'
  • Event: 'displayOrient'
  • Event: 'displayMove'
  • sdl.video.displays
  • sdl.video.windows
  • sdl.video.focused
  • sdl.video.hovered
  • sdl.video.createWindow([options])
  • class Window
    • Event: 'show'
    • Event: 'hide'
    • Event: 'expose'
    • Event: 'minimize'
    • Event: 'maximize'
    • Event: 'restore'
    • Event: 'move'
    • Event: 'resize'
    • Event: 'displayChange'
    • Event: 'focus'
    • Event: 'blur'
    • Event: 'hover'
    • Event: 'leave'
    • Event: 'beforeClose'
    • Event: 'close'
    • Event: 'keyDown'
    • Event: 'keyUp'
    • Event: 'textInput'
    • Event: 'mouseButtonDown'
    • Event: 'mouseButtonUp'
    • Event: 'mouseMove'
    • Event: 'mouseWheel'
    • Event: 'dropBegin'
    • Event: 'dropText'
    • Event: 'dropFile'
    • Event: 'dropComplete'
    • window.id
    • window.title
    • window.setTitle(title)
    • window.x
    • window.y
    • window.setPosition(x, y)
    • window.width
    • window.height
    • window.pixelWidth
    • window.pixelHeight
    • window.setSize(width, height)
    • window.setSizeInPixels(pixelWidth, pixelHeight)
    • window.display
    • window.visible
    • window.show([show])
    • window.hide()
    • window.fullscreen
    • window.setFullscreen(fullscreen)
    • window.resizable
    • window.setResizable(resizable)
    • window.borderless
    • window.alwaysOnTop
    • window.setBorderless(borderless)
    • window.accelerated
    • window.setAccelerated(accelerated)
    • window.vsync
    • window.setVsync(vsync)
    • window.opengl
    • window.webgpu
    • window.native
    • window.maximized
    • window.maximize()
    • window.minimized
    • window.minimize()
    • window.restore()
    • window.focused
    • window.focus()
    • window.hovered
    • window.skipTaskbar
    • window.popupMenu
    • window.tooltip
    • window.utility
    • window.render(width, height, stride, format, buffer[, options])
    • window.setIcon(width, height, stride, format, buffer)
    • window.flash(untilFocused)
    • window.stopFlashing()
    • window.destroyed
    • window.destroy()
    • window.destroyGently()
• sdl.keyboard
  • Virtual keys
  • Enum: SCANCODE
  • sdl.keyboard.getKey(scancode)
  • sdl.keyboard.getScancode(key)
  • sdl.keyboard.getState()
• sdl.mouse
  • Enum: BUTTON
  • sdl.mouse.getButton(button)
  • sdl.mouse.position
  • sdl.mouse.setPosition(x, y)
  • sdl.mouse.setCursor(cursor)
  • sdl.mouse.resetCursor()
  • sdl.mouse.setCursorImage(width, height, stride, format, buffer, x, y)
  • sdl.mouse.showCursor([show])
  • sdl.mouse.hideCursor()
  • sdl.mouse.redrawCursor()
  • sdl.mouse.capture([capture])
  • sdl.mouse.uncapture()
• sdl.joystick
  • Hat positions
  • Power levels
  • Event: 'deviceAdd'
  • Event: 'deviceRemove'
  • sdl.joystick.devices
  • sdl.joystick.openDevice(device)
  • class JoystickInstance
    • Event: 'axisMotion'
    • Event: 'ballMotion'
    • Event: 'buttonDown'
    • Event: 'buttonUp'
    • Event: 'hatMotion'
    • Event: 'close'
    • joystickInstance.device
    • joystickInstance.firmwareVersion
    • joystickInstance.serialNumber
    • joystickInstance.axes
    • joystickInstance.balls
    • joystickInstance.buttons
    • joystickInstance.hats
    • joystickInstance.power
    • joystickInstance.setPlayer(index)
    • joystickInstance.resetPlayer()
    • joystickInstance.hasLed
    • joystickInstance.setLed(red, green, blue)
    • joystickInstance.hasRumble
    • joystickInstance.rumble([low[, high[, duration]]])
    • joystickInstance.stopRumble()
    • joystickInstance.hasRumbleTriggers
    • joystickInstance.rumbleTriggers([left[, right[, duration]]])
    • joystickInstance.stopRumbleTriggers()
    • joystickInstance.closed
    • joystickInstance.close()
• sdl.controller
  • Event: 'deviceAdd'
  • Event: 'deviceRemove'
  • sdl.controller.addMappings(mappings)
  • sdl.controller.devices
  • sdl.controller.openDevice(device)
  • class ControllerInstance
    • Event: 'axisMotion'
    • Event: 'buttonDown'
    • Event: 'buttonUp'
    • Event: 'remap'
    • Event: 'close'
    • controllerInstance.device
    • controllerInstance.firmwareVersion
    • controllerInstance.serialNumber
    • controllerInstance.steamHandle
    • controllerInstance.axes
    • controllerInstance.buttons
    • controllerInstance.power
    • controllerInstance.setPlayer(index)
    • controllerInstance.resetPlayer()
    • controllerInstance.hasLed
    • controllerInstance.setLed(red, green, blue)
    • controllerInstance.hasRumble
    • controllerInstance.rumble([low[, high[, duration]]])
    • controllerInstance.stopRumble()
    • controllerInstance.hasRumbleTriggers
    • controllerInstance.rumbleTriggers([left[, right[, duration]]])
    • controllerInstance.stopRumbleTriggers()
    • controllerInstance.closed
    • controllerInstance.close()
• sdl.sensor
  • sdl.sensor.STANDARD_GRAVITY
  • sdl.sensor.devices
  • sdl.sensor.openDevice(device)
  • class SensorInstance
    • Event: 'update'
    • sensorInstance.device
    • sensorInstance.data
    • sensorInstance.closed
    • sensorInstance.close()
• sdl.audio
  • Audio data
  • Sample formats
  • Event: 'deviceAdd'
  • Event: 'deviceRemove'
  • sdl.audio.bytesPerSample(format)
  • sdl.audio.minSampleValue(format)
  • sdl.audio.maxSampleValue(format)
  • sdl.audio.zeroSampleValue(format)
  • sdl.audio.readSample(format, buffer[, offset])
  • sdl.audio.writeSample(format, buffer, value[, offset])
  • sdl.audio.devices
  • sdl.audio.openDevice(device[, options])
  • class AudioInstance
    • Event: 'close'
    • audioInstance.id
    • audioInstance.channels
    • audioInstance.frequency
    • audioInstance.format
    • audioInstance.bytesPerSample
    • audioInstance.minSampleValue
    • audioInstance.maxSampleValue
    • audioInstance.zeroSampleValue
    • audioInstance.readSample(buffer[, offset])
    • audioInstance.writeSample(buffer, value[, offset])
    • audioInstance.buffered
    • audioInstance.playing
    • audioInstance.play([play])
    • audioInstance.pause()
    • audioInstance.queued
    • audioInstance.clearQueue()
    • audioInstance.closed
    • audioInstance.close()
  • class AudioPlaybackInstance extends AudioInstance
    • playbackInstance.enqueue(buffer[, bytes])
  • class AudioRecordingInstance extends AudioInstance
    • recordingInstance.dequeue(buffer[, bytes])
• sdl.clipboard
  • Event: 'update'
  • sdl.clipboard.text
  • sdl.clipboard.setText(text)
• sdl.power
  • sdl.power.info
• helpers

sdl

sdl.info

• <object>
  • version: <object>
    • compile: <object> The SDL version the bindings were compiled against.
      • major, minor, patch: <Semver> The components of the version.
    • runtime: <object> The SDL version of the dynamic library the is loaded.
      • major, minor, patch: <Semver> The components of the version.
  • platform: <string> The name of the platform we are running on. Possible values are: 'Linux', 'Windows', and 'Mac OS X'.
  • drivers: <object>
    • video: <object>
      • all: <string>[] A list of all video drivers.
      • current: <string>|<null> The video driver that is currently selected.
    • audio: <object>
      • all: <string>[] A list of all audio drivers.
      • current: <string>|<null> The audio driver that is currently selected.

This object is filled with the information produced during the initialization of SDL. All the values will remain constant throughout the execution of the program. If you want to initialize SDL with drivers other than the default ones, you can do so via its environment variables.

Note that the current video or audio driver can be null. This can happen on systems that don't have any compatible devices, such as on a CI pipeline.

Sample data for Ubuntu:

{
  version: {
    compile: { major: 2, minor: 0, patch: 10 },
    runtime: { major: 2, minor: 0, patch: 10 },
  },
  platform: 'Linux',
  drivers: {
    video: {
      all: [ 'x11', 'wayland', 'dummy' ],
      current: 'x11',
    },
    audio: {
      all: [ 'pulseaudio', 'alsa', 'sndio', 'dsp', 'disk', 'dummy' ],
      current: 'pulseaudio',
    },
  },
}

sdl.video

Image data

There are 3 places in the API where you will need to provide an image to the library:

• window.render()
• window.setIcon()
• mouse.setCursorImage()

All three of these functions accept the image as a series of arguments:

• width: <number> The width of the image in pixels.
• height: <number> The height of the image in pixels.
• stride: <number> How many bytes each row of the image takes up in the buffer. This is usually equal to width * bytesPerPixel, but can be larger if the rows of the buffer are padded to always be some multiple of bytes.
• format:<PixelFormat> The binary representation of the data in the buffer.
• buffer: <Buffer> Holds the actual pixel data for the image, in the format and layout specified by all the above arguments.

So for example, to fill the window with a red+green gradient you could do:

const { pixelWidth: width, pixelHeight: height } = window
const stride = width * 4
const buffer = Buffer.alloc(stride * height)

let offset = 0
for (let i = 0; i < height; i++) {
  for (let j = 0; j < width; j++) {
    buffer[offset++] = Math.floor(256 * i / height) // R
    buffer[offset++] = Math.floor(256 * j / width)  // G
    buffer[offset++] = 0                            // B
    buffer[offset++] = 255                          // A
  }
}

window.render(width, height, stride, 'rgba32', buffer)

High-DPI

On a high-dpi display, windows have more pixels that their width and height would indicate. On such systems width and height (and all other measurements such as x and y) are in "points". Points are abstract and don't have to correspond to pixels. If you need to know a window's width and height in pixels, you should use the pixelWidth and pixelHeight properties. You should be doing this always, since you don't know beforehand if your program will be running on a high-dpi system.

Pixel formats

String values used to represent how the pixels of an image are stored in a Buffer.

Event: 'displayAdd'

• device: <object>: An object from sdl.video.displays indicating the display that caused the event.

Fired when a display is added to the system. Check sdl.video.displays to get the new list of displays.

Event: 'displayRemove'

• device: <object>: An object from sdl.video.displays indicating the display that caused the event.

Fired when a display is removed from the system. Check sdl.video.displays to get the new list of displays.

Event: 'displayOrient'

• device: <object>: An object from sdl.video.displays indicating the display that caused the event.
• orientation: <string>: The display's new orientation.

Fired when a display changes orientation.

Event: 'displayMove'

• device: <object>: An object from sdl.video.displays indicating the display that caused the event.

Fired when a display changes position.

sdl.video.displays

• <object>[]
  • name: <string> The name of the display.
  • format:<PixelFormat> The pixel format of the display.
  • frequency: <number> The refresh rate of the display.
  • geometry: <object> The desktop region represented by the display.
    • x, y, width, height: <Rect> The position and size of the display's geometry.
  • usable: <object> Similar to geometry, but excludes areas taken up by the OS or window manager such as menus, docks, e.t.c.
    • x, y, width, height: <Rect> The position and size of the display's usable region.
  • 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.
    • horizontal: <number> The horizontal density.
    • vertical: <number> The vertical density.
    • diagonal: <number> The diagonal density.
  • orientation: <string>|<null> The orientation of the display.

A list of all detected displays.

Possible values for orientation are null if it is unknown, or one of:

Sample output for two side-to-side monitors is below. Notice how the geometries don't overlap:

[
  {
    name: '0',
    format: 'rgb888',
    frequency: 60,
    geometry: { x: 0, y: 0, width: 1920, height: 1080 },
    usable: { x: 0, y: 27, width: 1920, height: 1053 },
    dpi: { horizontal: 141.76, vertical: 142.13, diagonal: 141.85 }
  },
  {
    name: '1',
    format: 'rgb888',
    frequency: 60,
    geometry: { x: 1920, y: 0, width: 1920, height: 1080 },
    usable: { x: 1920, y: 27, width: 1920, height: 1053 },
    dpi: { horizontal: 141.76, vertical: 142.13, diagonal: 141.85 }
  },
]

sdl.video.windows

• <Window>[]

A list of all open windows.

sdl.video.focused

• <Window>|<null>

The window that has the current keyboard focus, or null if no window has the keyboard focus.

sdl.video.hovered

• <Window>|<null>

The window that the mouse is hovered over, or null if the mouse is not over a window.

sdl.video.createWindow(options)

• options: <object>
  • title: <string> Will appear in the window's title bar. Default: ''
  • display: <number> An object from sdl.video.displays to specify in which display the window will appear (if you have multiple displays). Default: sdl.video.displays[0]
  • x: <number> The x position in which the window will appear relative to the screen, or null for centered. Default: null
  • y: <number> The y position in which the window will appear relative to the screen, or null for centered. Default: null
  • width: <number> The width of the window. Default: 640
  • height: <number> The height of the window. Default: 480
  • visible: <boolean> Set to false to create a hidden window that will only be shown when you call window.show(). Default: true
  • fullscreen: <boolean> Set to true to create the window in fullscreen mode. Default: false
  • resizable: <boolean> Set to true to allow resizing the window by dragging its borders. Default: false
  • borderless: <boolean> Set to true to completely hide the window's borders and title bar. Default: false
  • alwaysOnTop: <boolean> Set to true to always show this window above others. Default: false
  • accelerated: <boolean> Set to false to disable hardware accelerated rendering. Default: true
  • vsync: <boolean> Set to false to disable frame rate synchronization. Default: true
  • opengl: <boolean> Set to true to create an OpenGL-compatible window (for use with @kmamal/gl). Default: false
  • webgpu: <boolean> Set to true to create an WebGPU-compatible window (for use with @kmamal/gpu). Default: false
  • skipTaskbar: <boolean> X11 only. Set to true to not add this window to the taskbar. Default: false
  • popupMenu: <boolean> X11 only. Set to true to treat this window like a popup menu. Default: false
  • tooltip: <boolean> X11 only. Set to true to treat this window like a tooltip. Default: false
  • utility: <boolean> X11 only. Set to true to treat this window like a utility window. Default: false
• Returns: <Window> an object representing the new window.

Creates a new window.

The following restrictions apply:

• If you specify the display option, you can't also specify the x or y options, and vice-versa.
• The resizable and borderless options are mutually exclusive.
• The opengl and webgpu options are mutually exclusive.
• The vsync option only applies to windows that are also accelerated.
• The accelerated and vsync options have no effect if either opengl or webgpu is also specified.

If you set the opengl or webgpu options, then you can only render to the window with OpenGL/WebGPU calls. Calls to render() will fail.

class Window

This class is not directly exposed by the API so you can't use it with the new operator. Instead, objects returned by sdl.video.createWindow() are of this type.

Event: 'show'

Fired when a window becomes visible.

Event: 'hide'

Fired when a window becomes hidden.

Event: 'expose'

Fired when a window becomes exposed and should be redrawn.

Event: 'minimize'

Fired when a window becomes minimized.

Event: 'maximize'

Fired when a window becomes maximized.

Event: 'restore'

Fired when a window gets restored.

Event: 'move'

• x: <number> The window's new x position, relative to the screen.
• y: <number> The window's new y position, relative to the screen.

Fired when the window changes position.

Event: 'resize'

• width: <number> The window's new width.
• height: <number> The window's new height.
• pixelWidth: <number> The window's new width in pixels. See high-dpi.
• pixelHeight: <number> The window's new height in pixels. See high-dpi.

Fired when the window changes size.

Event: 'displayChange'

• display: <object> An object from sdl.video.displays indicating the window's new display.

Fired when a window moves from one display to another.

Event: 'focus'

Fired when a window gains the keyboard focus.

Event: 'blur'

Fired when a window loses the keyboard focus.

Event: 'hover'

Fired when the mouse enters the window.

Event: 'leave'

Fired when the mouse leaves the window.

Event: 'beforeClose'

• prevent: <function (void) => void> Call this to prevent the window from closing.

Fired to indicate that the user has requested the window to close (usually by clicking the "x" button). If you need to display any confirmation dialogs you should call event.prevent() and handle destruction manually. If prevent is not called, then this event will be followed by a 'close' event.

Event: 'close'

Indicates that the window is about to be destroyed. Handle any cleanup here.

Event: 'keyDown'

• scancode:<Scancode> The scancode of the key that caused the event.
• key:<Key>|<null> The virtual key that caused the event, or null if the physical key does not correspond to any virtual key.
• repeat: <boolean> Is true if the event was generated by holding down a key for a long time.
• shift: <boolean> Is true if the Shift key was pressed when the event was generated.
• ctrl: <boolean> Is true if the Ctrl key was pressed when the event was generated.
• alt: <boolean> Is true if the Alt key was pressed when the event was generated.
• super: <boolean> Is true if the "Windows" key was pressed when the event was generated.
• altgr: <boolean> Is true if the AltGr key was pressed when the event was generated.
• capslock: <boolean> Is true if CapsLock was active when the event was generated.
• numlock: <boolean> Is true if NumLock was active when the event was generated.

Fired when a key is pressed, and will also be fired repeatedly afterwards if the key is held down.

Event: 'keyUp'

• scancode:<Scancode> The scancode of the key that caused the event.
• key:<Key>|<null> The virtual key that caused the event, or null if the physical key does not correspond to any virtual key.
• shift: <boolean> Is true if the Shift key was pressed when the event was generated.
• ctrl: <boolean> Is true if the Ctrl key was pressed when the event was generated.
• alt: <boolean> Is true if the Alt key was pressed when the event was generated.
• super: <boolean> Is true if the "Windows" key was pressed when the event was generated.
• altgr: <boolean> Is true if the AltGr key was pressed when the event was generated.
• capslock: <boolean> Is true if CapsLock was active when the event was generated.
• numlock: <boolean> Is true if NumLock was active when the event was generated.

Fired when a key is released.

Event: 'textInput'

• text: <string> The unicode representation of the character that was entered.

Fired when the user enters text via the keyboard.

Event: 'mouseButtonDown'

• x: <number> The mouse's x position when the event happened, relative to the window.
• y: <number> The mouse's y position when the event happened, relative to the window.
• touch: <boolean> Will be true if the event was caused by a touch event.
• button:<sdl.mouse.BUTTON> The button that was pressed.

Fired when a mouse button is pressed.

Event: 'mouseButtonUp'

• x: <number> The mouse's x position when the event happened, relative to the window.
• y: <number> The mouse's y position when the event happened, relative to the window.
• touch: <boolean> Will be true if the event was caused by a touch event.
• button:<sdl.mouse.BUTTON> The button that was released.

Fired when a mouse button is released.

Event: 'mouseMove'

• x: <number> The mouse's x position when the event happened, relative to the window.
• y: <number> The mouse's y position when the event happened, relative to the window.
• touch: <boolean> Will be true if the event was caused by a touch event.

Fired when the mouse moves.

Event: 'mouseWheel'

• x: <number> The mouse's x position when the event happened, relative to the window.
• y: <number> The mouse's y position when the event happened, relative to the window.
• touch: <boolean> Will be true if the event was caused by a touch event.
• dx: <number> The wheel's x movement, relative to its last position.
• dy: <number> The wheel's y movement, relative to its last position.
• flipped: <boolean> Will be true if the underlying platform reverses the mouse wheel's scroll direction. Multiply dx and dy by -1 to get the correct values.

Fired when the mouse wheel is scrolled.

Event: 'dropBegin'

When dropping a set of items onto a window, first the 'dropBegin' event will be fired, then a number of 'dropText' and/or 'dropFile' events will be fired, corresponding to the contents of the drop, then finally the 'dropComplete' event will be fired.

Event: 'dropText'

• text: <string>: The text that was dropped onto the window.

Fired when one of the drops is a text item.

Event: 'dropFile'

• file: <string>: The path to the file that was dropped onto the window.

Fired when one of the drops is a file.

Event: 'dropComplete'

Fired after a set of items has been dropped on a window.

window.id

• <number>

A unique identifier for the window.

window.title

• <string>

The text that appears in the window's title bar.

window.setTitle(title)

• title: <string>: The new title.

Changes the text that appears in the window's title bar.

window.x

• <number>

The window's x position, relative to the screen.

window.y

• <number>

The window's y position, relative to the screen.

window.setPosition(x, y)

• x: <number>: The new x position, relative to the screen.
• y: <number>: The new y position, relative to the screen.

Moves the window to a new position on the screen.

window.width

• <number>

The window's width.

window.height

• <number>

The window's height.

window.pixelWidth

• <number>

The window's width in pixels. This will be larger than width on high-dpi displays.

window.pixelHeight

• <number>

The window's height in pixels. This will be larger than height on high-dpi displays.

window.setSize(width, height)

• width: <number>: The new width.
• height: <number>: The new height.

Changes the size of the window.

window.setSizeInPixels(pixelWidth, pixelHeight)

• pixelWidth: <number>: The new width in pixels.
• pixelHeight: <number>: The new height in pixels.

Changes the size of the window. This function only behaves differently from window.setSize() for high-dpi displays.

window.display

• <object>

An object from sdl.video.displays indicating the display this window belongs to. If the window spans multiple displays, then the display containing the center of the window is returned.

window.visible

• <boolean>

Will be true if the window is visible.

window.show(show)

• show: <boolean> Set to true to make the window visible, false to hide it. Default: true

Shows or hides the window.

window.hide()

Equivalent to window.show(false).

window.fullscreen

• <boolean>

Will be true if the window is fullscreen. A fullscreen window is displayed over the entire screen.

window.setFullscreen(fullscreen)

• fullscreen: <boolean> The new value of the property.

Changes the window's fullscreen property.

window.resizable

• <boolean>

Will be true if the window is resizable. A resizable window can be resized by dragging it's borders.

window.setResizable(resizable)

• resizable: <boolean> The new value of the property.

Changes the window's resizable property.

window.borderless

• <boolean>

Will be true if the window is borderless. A borderless window has no borders or title bar.

window.setBorderless(borderless)

• borderless: <boolean> The new value of the property.

Changes the window's borderless property.

window.alwaysOnTop

• <boolean>

Will be true if the window was created with alwaysOnTop: true. Such a window will always be shown above other windows.

window.accelerated

• <boolean>

Will be true if the window is using hardware accelerated rendering.

window.setAccelerated(accelerated)

• accelerated: <boolean> The new value of the property.

Changes the window's accelerated property.

If you have set the opengl or webgpu options, then calls to this function will fail.

window.vsync

• <boolean>

Will be true if the window is using vsync. A window with vsync enabled will have its frame rate synchronized to the display's refresh rate to prevent tearing. Note that vsync can only be used if that window is also accelerated

window.setVsync(vsync)

• vsync: <boolean> The new value of the property.

Changes the window's vsync property.

If you have set the opengl or webgpu options, then calls to this function will fail.

window.opengl

• <boolean>

Will be true if the window was created in OpenGl mode. In OpenGL mode, you can only render to the window with OpenGL calls. Calls to render() will fail.

window.webgpu

• <boolean>

Will be true if the window was created in WebGPU mode. In WebGPU mode, you can only render to the window with WebGPU calls. Calls to render() will fail.

window.native

• <object>
  • handle : <Buffer> The platform-specific handle of the window.

The native type of handle is HWND on Windows, NSView* on macOS, and Window (unsigned long) on Linux. It should work exactly like the win.getNativeWindowHandle() electron method.

This object might also include extra fields that are used for passing to @kmamal/gl or @kmamal/gpu. Please ignore these.

window.maximized

• <boolean>

Will be true if the window is maximized.

window.maximize()

Maximizes the window.

window.minimized

• <boolean>

Will be true if the window is minimized.

window.minimize()

Minimizes the window.

window.restore()

Restores the window so it's neither minimized nor maximized.

window.focused

• <boolean>

Will be true if the window has keyboard input.

window.focus()

Gives the window the keyboard focus.

window.hovered

• <boolean>

Will be true if the mouse is over the window.

window.skipTaskbar

• <boolean>

X11 only. Will be true if the window was created with skipTaskbar: true. Such a window will not be added to the taskbar.

window.popupMenu

• <boolean>

X11 only. Will be true if the window was created with popupMenu: true. Such a window will always be treated as a popup menu.

window.tooltip

• <boolean>

X11 only. Will be true if the window was created with tooltip: true. Such a window will always be treated as a tooltip.

window.utility

• <boolean>

X11 only. Will be true if the window was created with utility: true. Such a window will always be treated as a utility window.

window.render(width, height, stride, format, buffer, options)

• width, height, stride, format, buffer:<Image> The image to display on the window.
• options: <object>
  • scaling: <string> How to scale the image to match the window size. Default: 'nearest'
  • dstRect: <object> Where exactly on the window to draw the image. Default: whole window.
    • x, y, width, height: <rect> The components of the rectangle.

Displays an image in the window.

By default the image is displayed over the entire surface of the window. You can pass the optional dstRect parameter to set where exactly on the window to display the image. The rest of the window will be filled with black.

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. The scaling argument controls how exactly the scaling is implemented. Possible values are:

If the window was created with either of the opengl or webgpu options, then you can only render to the window with OpenGL/WebGPU calls. Calls to render() will fail.

window.setIcon(width, height, stride, format, buffer)

• width, height, stride, format, buffer:<Image> The image to display as the icon of the window.

Set's the window's icon, usually displayed in the title bar and the taskbar.

window.flash(untilFocused)

• untilFocused: <boolean> Whether to keep flashing the window until the user focuses it. Default: false

Flash the window briefly to get attention. If untilFocused is set, the window will flash until the user focuses it.

window.stopFlashing()

Stop the window from flashing.

window.destroyed

• <boolean>

Will be true if the window is destroyed. A destroyed window object should not be used any further.

window.destroy()

Destroys the window.

window.destroyGently()

Asks before destroying the window. The difference between this function and destroy() is that this function will first make the window emit the 'beforeClose' event, giving you a chance to prevent the window from being destroyed.

sdl.keyboard

There are three levels at which you can deal with the keyboard: physical keys (scancodes), virtual keys (keys), and text ('textInput' events).

On the physical level, each of the physical keys corresponds to a number: the key's scancode. For any given keyboard, the same key will always produce the same scancode. 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' and 'keyUp' events.

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 so you should be able to derive some meaning from the scancodes if your keyboard is compatible.

More commonly, you don't care about the physical key itself but about the "meaning" associated with each key: the character that it produces ("a", "b", "@", " ", .e.t.c) or the function that it corresponds to ("Esc", "F4", "Ctrl", e.t.c.). Your operating system provides a "keyboard mapping" that associates physical keys with their corresponding meaning. 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). These meanings are represented as virtual key strings. 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' and 'keyUp' events.

Note that not all physical keys correspond to a well-defined meaning and thus don't have a virtual key value associated with them. The key events for these keys will have a null value for the key property.

But sometimes the application doesn't care about individual keys at all, but about the resulting text that the user is entering. 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. Trying to handle text input by manually translating key presses to text is not a very viable solution. It's better to let the OS handle all the text logic, and get the final text by handling the rasulting ('textInput') events.

Virtual keys

String values used to represent virtual keys in the context of the current keyboard mapping. Note that some keys do not correspond to any virtual key. A Key can be either one of the values below or any unicode character. Keys that produce characters are represented by that character. All others are represented by one of these values:

'&&', '+/-', '||', '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'.

Enum: SCANCODE

Used to represent physical keys on the keyboard. The same key will always produce the same scancode. Values are based on the USB usage page standard.