DOCSEARCHbyAlgolia
Submit Docs

Simple DirectMedia Layer (SDL)

repository·main·Indexed 12 days ago

https://github.com/libsdl-org/sdl

A cross-platform development library providing low-level access to audio, keyboard, mouse, joystick, and graphics hardware. Written in C and compatible with C++, it is widely used for games, emulators, and video playback software across Windows, macOS, Linux, iOS, Android, and consoles.

Tokens
64.9K
Snippets
153
Records
289
Agent score
93%

What's inside SDL

  1. Overview of Simple DirectMedia Layer (SDL)

    main

    Simple DirectMedia Layer (SDL) is a cross-platform development library that provides low-level access to hardware including audio, keyboard, mouse, joystick, and graphics. It is widely used for video playback software, emulators, and games.

    Key characteristics:

    • Cross-platform: Supports Windows, macOS, Linux, iOS, Android, Xbox, PlayStation 4/5, Nintendo Switch, and more.
    • Language Support: Written in C, works natively with C++, and has bindings for languages like C# and Python.
    • License: Distributed under the zlib license.

  2. Overview of SDL GDK Support

    main

    SDL supports running applications via Microsoft's Game Development Kit (GDK) for both Windows GDK and Xbox One/Xbox Series (GDKX).

    Key distinctions:

    • Windows GDK: Supports the full set of Win32 APIs, renderers, controllers, and input devices, similar to the standard Windows x64 build.
    • Xbox (GDKX): Requires licensed Xbox developer access to the GDKX libraries to build Xbox targets.
    • Platform Detection: You can use compile-time macros to detect the platform:
      • SDL_PLATFORM_GDK: Defined on all GDK platforms.
      • SDL_PLATFORM_WINGDK: Defined specifically on Windows GDK.

  3. Supported and Unsupported Platforms for SDL3

    main

    SDL3 supports a wide range of platforms, including mobile (Android, iOS, tvOS, visionOS), desktop (Windows XP+, macOS 10.14+, Linux, FreeBSD, OpenBSD, NetBSD), web (Emscripten), and various consoles (Nintendo Switch/Switch 2, PlayStation 4/5, Xbox, etc.).

    Note on Testing: SDL maintainers do not officially test every platform. If you encounter issues on a supported platform, you are encouraged to report them via GitHub issues.

    Unsupported Platforms: Platforms such as Google Stadia, NaCL, OS/2, WinPhone, WinRT/UWP, and Pandora are not actively supported in SDL3. If you must target these systems, you may need to use the incompatible SDL2 API.

  4. Use Wayland as the default windowing system in SDL3

    main
    In SDL3, Wayland is favored over X11 by default for communicating with desktop compositors. While it works well for most applications, developers should be aware that Wayland has different architectural constraints compared to X11, which may result in different behaviors regarding window positioning, decorations, and input handling.

  5. License for SDL example code

    main

    All code located within the examples/ directory is in the public domain. You are free to copy, paste, modify, or sell this code, even within closed-source projects, without requirement for attribution.

    Note: This applies only to the examples/ directory. The core SDL library is licensed under the zlib license.

  6. Overview of HIDAPI back-ends and platform support

    main

    HIDAPI is a multi-platform library for interfacing with USB and Bluetooth HID-Class devices on Windows, Linux, FreeBSD, and macOS. It can be used as a shared library (.so, .dll, or .dylib) or embedded directly into an application by adding a single source file (per platform) and a single header.

    Supported Back-ends

    • Windows: Uses hid.dll.
    • macOS: Uses IOHidManager.
    • Linux/FreeBSD/Other UNIX-like:
      • Linux/hidraw: Uses the kernel's hidraw driver. Supports both USB and Bluetooth HID devices. Note that devices blacklisted from having hidraw nodes (like keyboards and mice) will not work. Requires kernel 2.6.39+.
      • libusb: Uses libusb-1.0 to communicate directly to USB devices. This back-end does not work with Bluetooth devices.

    To choose a specific Linux backend, link against either libhidapi-libusb or libhidapi-hidraw at link time.

  7. How memory management and the fat DS trick work on DOS

    main

    The DOS port produces 32-bit protected-mode DPMI executables. It relies on the "fat DS" nearptr trick to convert physical addresses into usable C pointers, enabling direct access to the VESA linear framebuffer and DMA buffers without manual segment descriptor manipulation.

    Usage Requirements:

    • If you use SDL_RunApp(), the fat DS trick is enabled automatically via SDL_main.h.
    • If you define SDL_MAIN_HANDLED, you must manually call __djgpp_nearptr_enable() before initializing SDL. Failure to do so will cause video initialization to fail.

  8. Understand Nintendo 3DS threading and yielding

    main

    The Nintendo 3DS uses a cooperative threading model on a single core. Threads will not yield control unless they perform a manual yield or a blocking wait.

    To avoid starving other threads, use these yielding functions:

    • SDL_Delay functions
    • Blocking waits: SDL_LockMutex, SDL_WaitSemaphore, SDL_WaitCondition, SDL_WaitThread
    • SDL_TryWaitSemaphore (yields if it fails to acquire the semaphore)
    • SDL_WaitSemaphoreTimeout (yields if it fails to acquire the semaphore)

  10. How SDL3 audio devices and streams work

    main

    SDL3 introduces several conceptual changes to the audio subsystem:

    • Terminology: "Capture" devices are now recording devices, and "output" devices are now playback devices.
    • Device IDs: SDL_AudioDeviceID now represents both a logical device handle (returned by SDL_OpenAudioDevice) and a physical hardware instance ID. They are largely interchangeable. Devices are opened by physical instance ID rather than string names.
    • Initialization: SDL3 will not implicitly initialize the audio subsystem. You must explicitly call SDL_Init(SDL_INIT_AUDIO) or SDL_InitSubSystem(SDL_INIT_AUDIO).
    • Concurrency: SDL_LockAudioDevice() and SDL_UnlockAudioDevice() have been removed. SDL_AudioStream is thread-safe. If you need a lock for a specific callback, use SDL_LockAudioStream().
    • AudioSpec: The SDL_AudioSpec struct is simplified; it only contains format, channels, and freq. The samples field is now managed by SDL3. To control latency, use the SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES hint.

  11. How SDL callback-based applications work

    main

    SDL supports an alternative program structure to the traditional main function. Instead of a single entry point, the application is structured as a collection of callbacks. This pattern is particularly useful for web applications (via Emscripten) and helps cleanly separate the four logical stages of an application lifecycle:

    1. Program startup: Initialization logic.
    2. Event handling: Processing user input and system events.
    3. Frame logic: The core logic executed once per frame (often referred to as SDL_AppIterate).
    4. Program shutdown: Cleanup logic.

    For a detailed technical specification of these callbacks, refer to docs/README-main-functions.md or the official SDL wiki.

  12. Understand SDL's odd/even versioning policy

    main

    Since version 3.2.0, SDL uses an "odd/even" versioning policy to distinguish between stable production releases and development prereleases. This helps developers decide which version to target based on their stability requirements.

    Stable Releases

    A version is considered stable and suitable for production if both the minor version (second part) and the patch version (third part) are divisible by 2 (e.g., 3.2.6, 3.4.0).

    • Patch versions (e.g., 3.2.8): These are bugfix releases. They are backwards-compatible (programs built against 3.2.0 will work with 3.2.8), but not necessarily forwards-compatible.
    • Minor versions (e.g., 3.4.x): These indicate significant changes or new functionality. They are backwards-compatible (programs built against 3.2.x will work with 3.4.x), but not necessarily forwards-compatible.

    Prerelease Versions

    A version is a development prerelease if the minor version or patch version is not divisible by 2 (e.g., 3.2.9, 3.3.x). These are not suitable for stable software distributions and should be used with caution.

    • Compatibility: Prereleases are backwards-compatible with older stable branches (e.g., 3.2.x works with 3.3.x), but they are not guaranteed to be backwards-compatible with each other (APIs may change between 3.3.0 and 3.3.1).
    • Usage Recommendation: Only use prereleases if you can guarantee a prompt upgrade to the subsequent stable release (e.g., upgrading from 3.3.x to 3.4.0 when it arrives).