DOCSEARCHbyAlgolia
Submit Docs

SDL Wiki

repository·main·Indexed 41 days ago

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

Documentation and migration guides for transitioning from SDL2 to SDL3, including detailed API references for satellite libraries such as SDL_image and SDL_mixer 2.0. Covers image format initialization, audio channel management, and build configurations for CMake, Visual Studio, Xcode, and Android.

Tokens
305.2K
Snippets
590
Records
1.1K
Agent score
51%

What's inside SDL

  1. Overview of SDL3 GDK Support

    main

    This port enables SDL applications to run via Microsoft's Game Development Kit (GDK) on Windows and Xbox One/Xbox Series (GDKX).

    Key Platform 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 Macros:

    • SDL_PLATFORM_GDK: Defined on all GDK platforms.
    • SDL_PLATFORM_WINGDK: Defined specifically on Windows GDK. Use this to distinguish Windows-specific GDK code from other GDK platforms.

  2. What is SDL 2.0?

    main

    Simple DirectMedia Layer (SDL) is a cross-platform development library providing low-level access to hardware components including audio, keyboard, mouse, joystick, and graphics (via OpenGL and Direct3D). It is written in C and works natively with C++, but also has bindings for languages like C# and Python.

    Key Capabilities:

    • Graphics: 3D graphics (via OpenGL/Direct3D) and an accelerated 2D render API supporting rotation, scaling, and alpha blending.
    • Input: Support for mouse, keyboard, joystick, game controllers, and multitouch gestures. Events can be filtered or enabled/disabled using SDL_EventState().
    • Audio: Supports 8-bit/16-bit, mono, stereo, and 5.1 surround sound. Audio runs in a separate thread using a user callback mechanism.
    • Concurrency: Provides APIs for thread creation, thread-local storage, mutexes, semaphores, condition variables, and atomic operations.
    • System Utilities: File I/O abstraction, shared object loading (DLL, .dylib, .so), timers, CPU feature detection, and endianness handling.

  3. Overview of SDL_image 3.0 capabilities

    main

    SDL_image 3.0 is a library used to load various image formats directly into SDL surfaces.

    Supported Formats:

    • Standard: BMP, GIF, JPEG, LBM, PCX, PNG, PNM (PPM/PGM/PBM), QOI, TGA, XCF, XPM, and simple SVG.
    • Optional (depending on build options): AVIF, JPEG-XL, TIFF, and WebP.

    Licensing: SDL_image is distributed under the zlib license, allowing free use in any software.

  5. Overview of SDL_mixer 3.0

    main
    SDL_mixer 3.0 is an audio management library designed for SDL3-based games. It provides audio file decoding for multiple formats (including WAV, MP3, and Ogg Vorbis) and supports sample-perfect mixing of multiple audio sources with various effects. The library is distributed under the zlib license.

  6. Overview of SDL 2.0 key features

    main

    SDL 2.0 introduced several major capabilities compared to SDL 1.2, including:

    • Graphics & Rendering: Full 3D hardware acceleration, support for OpenGL 3.0+ (various profiles), OpenGL ES, and a simple 2D rendering API (using Direct3D, OpenGL, OpenGL ES, or software).
    • Windowing & Display: Support for multiple windows, multiple displays, shaped windows, and improved fullscreen support.
    • Input: Simplified Game Controller API (while retaining the Joystick API), touch support (multitouch, gestures), better keyboard support (scancodes vs keycodes), and basic Drag'n'Drop support.
    • Audio: Support for multiple audio devices, audio recording, and 32-bit audio (int and float).
    • Platform Support: Android, iOS, Emscripten, and Native Client.
    • System & Utilities: Atomic operations, power management, message boxes, clipboard support, and proper Unicode/IME support.

  7. Overview of SDL 2.0 new features

    main

    SDL 2.0 introduces significant improvements over SDL 1.2, focusing on hardware acceleration, multi-device support, and modern platform compatibility. Key improvements include:

    • Graphics: Hardware 3D acceleration, OpenGL 3.0+ support (multiple profiles), OpenGL ES, a simple 2D API (supporting Direct3D, OpenGL, OpenGL ES, or software rendering), and windows with arbitrary shapes.
    • Display & Windowing: Support for multiple windows and multiple screens, improved fullscreen support, and message windows.
    • Audio: Support for multiple audio devices, audio recording, and 32-bit audio (both integer and float).
    • Input: Simplified Game Controller API (while maintaining the Joystick API), touch control support (multi-touch, gestures), improved keyboard support (scancodes vs keycodes), and basic Drag'n'Drop.
    • Platforms: Support for Android, iOS, Emscripten, and Native Client.
    • System & Utilities: Atomic operations, power management (e.g., battery status), clipboard support, IME and Unicode input, and XInput/XAudio2 support on Windows.
    • Licensing: The license has changed from LGPL to zlib.

    For a more exhaustive list of all features, refer to the Introduction page.

  8. What is Simple DirectMedia Layer (SDL)?

    main

    Simple DirectMedia Layer is a cross-platform development library providing low-level access to hardware including:

    • Audio
    • Keyboard
    • Mouse
    • Joystick
    • Graphics hardware (via OpenGL, Direct3D, Metal, or Vulkan)

    Supported Platforms:

    • Windows
    • macOS
    • Linux
    • iOS
    • Android

    Language Support:

    • Written in C
    • Works natively with C++
    • Bindings available for C#, Python, and others.

    Licensing: SDL 2.0 is distributed under the zlib license, allowing free use in any software.

  9. Overview of SDL 2D Rendering API

    main

    The SDL 2D rendering API is designed to accelerate simple 2D operations. It provides hardware-accelerated support for drawing primitives and textures.

    Supported Features:

    • Single pixel points and lines
    • Filled rectangles
    • Texture images
    • 2D polygons

    Rendering Modes: Primitives and textures can be drawn using opaque, blended, or additive modes. Textures specifically support color tinting, alpha modulation, and stretching with linear interpolation.

    Important Constraint: All rendering functions must be called from the main thread.

  10. Overview of the SDL 2D Rendering API

    main

    The CategoryRender header provides an API for accelerated 2D operations. It is designed for simple 2D tasks and includes support for:

    • Primitives: Single pixel points, single pixel lines, filled rectangles, and 2D polygons.
    • Textures: Drawing texture images with support for opaque, blended, or additive modes.
    • Texture Manipulation: Applying color tints, alpha modulation, and linear interpolation stretching.

    Important Constraints:

    • Thread Safety: All rendering functions must be called from the main thread.
    • Use Case: For advanced requirements like 3D polygons or particle effects, use the SDL3 GPU API, OpenGL, Direct3D, or a dedicated 3D engine.

  11. What is SDL_ttf 3.0

    main

    SDL_ttf 3.0 is a library that provides a wrapper around FreeType and Harfbuzz, enabling SDL applications to render text using TrueType fonts.

    It is distributed under the zlib license. Note that while the library is free to use, you must comply with the specific licenses of any font files you include in your application (e.g., Microsoft fonts are not freely redistributable).

  12. Use the Nokia N-Gage SDL port

    main

    This is an SDL port specifically for the Nokia N-Gage platform. Unlike previous versions, this port features a dedicated rendering backend and a functional (though limited) audio interface. Note that the software renderer has been removed in this version to ensure a leaner and more efficient implementation.

    To build for this platform, you will need the Homebrew toolchain.