DOCSEARCHbyAlgolia
Submit Docs

SDL_image

repository·main·Indexed 21 days ago

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

A library used to load various image formats as SDL surfaces, extending SDL's native BMP loading capabilities. SDL_image 3.0 provides a unified interface for formats including PNG, AVIF, and WebP, and features automatic initialization and integration guides for CMake, Android Studio, Emscripten, Visual Studio, and Xcode.

Tokens
3.9K
Snippets
12
Records
26
Agent score
75%

What's inside SDL_image

  1. Overview of SDL_image 3.0

    main
    SDL_image is a library designed to load various image formats directly into SDL surfaces. It provides a unified interface for handling multiple image types, ranging from standard formats like BMP and PNG to more specialized formats like AVIF and WebP (depending on which optional libraries are linked during build/installation).

  3. Understand the SDL versioning policy

    main

    SDL uses an "odd/even" versioning policy to distinguish between stable production releases and development prereleases.

    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/Micro versions (third part): Indicate bugfix releases. These are backwards-compatible (e.g., code built against 3.2.0 works with 3.2.8), but not necessarily forwards-compatible.
    • Minor versions (second part): Increase for significant changes or new functionality. Newer minor versions are backwards-compatible with older ones in the same major series (e.g., code built against 3.2.x works with 3.4.x), but not forwards-compatible.

    Prereleases

    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.

    • Compatibility: Prereleases are backwards-compatible with older stable branches (e.g., 3.2.x code 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 Warning: Only use prereleases if you can promptly upgrade to the subsequent stable release (e.g., upgrading from 3.3.x to 3.4.0).

  6. Access SDL_image documentation and community support

    main

    For technical details and community interaction, use the following resources:

  7. Set up SDL_image with Visual Studio using subprojects

    main

    The recommended way to use SDL_image in Visual Studio is to include both SDL and SDL_image as subprojects within your solution.

    Follow these steps to configure a new C++ Empty Project:

    1. Project Creation: Create a new Visual Studio project using the C++ Empty Project template and add your source file (e.g., hello.c) to the Source Files.
    2. Add SDL Subproject: Right-click the solution, select Add > Existing Project, and navigate to the SDL VisualC/SDL directory to add SDL.vcxproj.
    3. Add SDL_image Subproject: Right-click the solution, select Add > Existing Project, and navigate to the SDL_image VisualC directory to add SDL_image.vcxproj.
    4. Configure SDL_image Dependencies: Select your SDL_image project, go to Project > Add Reference, and select SDL3.
    5. Configure SDL_image Include Paths: Select your SDL_image project, go to Project > Properties, set the configuration/platform filters to All Configurations and All Platforms, navigate to VC++ Directories, and update the Include Directories to point to your SDL include directories.
    6. Configure Main Project Dependencies: Select your main project, go to Project > Add Reference, and select both SDL3 and SDL3_image.
    7. Configure Main Project Include Paths: Select your main project, go to Project > Properties, set filters to All Configurations and All Platforms, navigate to VC++ Directories, and add both the SDL and SDL_image include directories to Include Directories.
    8. Build and Run.

  8. Enable support for AVIF, JPEG-XL, TIFF, and WebP

    main

    By default, SDL_image does not include support for AVIF, JPEG-XL, TIFF, or WebP to keep the library size small. To enable these formats:

    1. Run the external/download.sh script to fetch the necessary decoding libraries.
    2. Enable the corresponding SDLIMAGE_* CMake options (e.g., SDLIMAGE_AVIF, SDLIMAGE_JPEGXL, etc.) in your build configuration.

    You can also use the SDLIMAGE_VENDORED option to switch between using system-installed libraries or the vendored libraries downloaded via the script.

  11. Enable AVIF, JPEG-XL, and WebP support in Xcode

    main

    By default, support for AVIF, JPEG-XL, and WebP is not included in the Xcode project due to the size of the decoding libraries. To enable these formats:

    1. Run the script external/download.sh to fetch the necessary dependencies.
    2. Edit the configuration at the top of the Xcode project to enable the desired formats.
    3. Ensure you include the appropriate framework in your application to use these features.
    ./external/download.sh

  12. Build and use SDL_image with CMake

    main

    SDL_image can be integrated into your project using CMake. The general workflow is to use CMake to build the library and then link the resulting headers and library files to your own project.

    To build the included example programs alongside the library, enable the SDLIMAGE_SAMPLES option during the CMake configuration step.

    cmake -DSDLIMAGE_SAMPLES=ON ..