From d22f79116195dac75dd57ea8dc75e118ca13067b Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Wed, 22 Jan 2025 11:59:28 -0800
Subject: [PATCH] Updated installation documentation
---
INSTALL.md | 49 ++++++
README.md | 18 ++
README.txt | 38 ----
.../android/{README.md.in => INSTALL.md.in} | 162 +++++++++---------
build-scripts/pkg-support/mingw/INSTALL.md.in | 48 ++++++
build-scripts/pkg-support/msvc/INSTALL.md.in | 39 +++++
.../pkg-support/msvc/arm64/INSTALL.md.in | 13 ++
.../pkg-support/msvc/x64/INSTALL.md.in | 13 ++
.../pkg-support/msvc/x86/INSTALL.md.in | 13 ++
build-scripts/release-info.json | 24 ++-
docs/INTRO-androidstudio.md | 8 +
docs/INTRO-cmake.md | 59 +++++++
docs/INTRO-emscripten.md | 37 ++++
docs/INTRO-visualstudio.md | 17 ++
docs/INTRO-xcode.md | 19 ++
docs/README-emscripten.txt | 20 ---
docs/hello.c | 130 ++++++++++++++
17 files changed, 563 insertions(+), 144 deletions(-)
create mode 100644 INSTALL.md
create mode 100644 README.md
delete mode 100644 README.txt
rename build-scripts/pkg-support/android/{README.md.in => INSTALL.md.in} (61%)
create mode 100644 build-scripts/pkg-support/mingw/INSTALL.md.in
create mode 100644 build-scripts/pkg-support/msvc/INSTALL.md.in
create mode 100644 build-scripts/pkg-support/msvc/arm64/INSTALL.md.in
create mode 100644 build-scripts/pkg-support/msvc/x64/INSTALL.md.in
create mode 100644 build-scripts/pkg-support/msvc/x86/INSTALL.md.in
create mode 100644 docs/INTRO-androidstudio.md
create mode 100644 docs/INTRO-cmake.md
create mode 100644 docs/INTRO-emscripten.md
create mode 100644 docs/INTRO-visualstudio.md
create mode 100644 docs/INTRO-xcode.md
delete mode 100644 docs/README-emscripten.txt
create mode 100644 docs/hello.c
diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 000000000..3e30e7bf7
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,49 @@
+# To build and use SDL_image:
+
+SDL_image supports a number of development environments:
+- [CMake](docs/INTRO-cmake.md)
+- [Visual Studio on Windows](docs/INTRO-visualstudio.md)
+- [Xcode on Apple platforms](docs/INTRO-xcode.md)
+- [Android Studio](docs/INTRO-androidstudio.md)
+- [Emscripten for web](docs/INTRO-emscripten.md)
+
+SDL_image is also usable in other environments. The basic steps are to use CMake to build the library and then use the headers and library that you built in your project. You can search online to see if anyone has specific steps for your setup.
+
+# Documentation
+
+An API reference and additional documentation is available at:
+
+https://wiki.libsdl.org/SDL3_image
+
+# Example code
+
+There are simple example programs in the examples directory.
+
+If you're using CMake, you can build them adding `-DSDLIMAGE_SAMPLES=ON` to the CMake command line when building SDL_image.
+
+If you're using Visual Studio there are separate projects in the VisualC directory.
+
+If you're using Xcode there are separate projects in the Xcode directory.
+
+# Discussions
+
+## Discord
+
+You can join the official Discord server at:
+
+https://discord.com/invite/BwpFGBWsv8
+
+## Forums/mailing lists
+
+You can join SDL development discussions at:
+
+https://discourse.libsdl.org/
+
+Once you sign up, you can use the forum through the website or as a mailing list from your email client.
+
+## Announcement list
+
+You can sign up for the low traffic announcement list at:
+
+https://www.libsdl.org/mailing-list.php
+
diff --git a/README.md b/README.md
new file mode 100644
index 000000000..47426a49b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,18 @@
+
+SDL_image 3.0
+
+This is a simple library to load images of various formats as SDL surfaces.
+It can load BMP, GIF, JPEG, LBM, PCX, PNG, PNM (PPM/PGM/PBM), QOI, TGA, XCF, XPM, and simple SVG format images. It can also load AVIF, JPEG-XL, TIFF, and WebP images, depending on build options.
+
+The latest version of this library is available from GitHub:
+https://github.com/libsdl-org/SDL_image/releases
+
+Installation instructions and a quick introduction is available in
+[INSTALL.md](INSTALL.md)
+
+This library is distributed under the terms of the zlib license,
+available in [LICENSE.txt](LICENSE.txt).
+
+Enjoy!
+
+Sam Lantinga (slouken@libsdl.org)
diff --git a/README.txt b/README.txt
deleted file mode 100644
index 6490c77d3..000000000
--- a/README.txt
+++ /dev/null
@@ -1,38 +0,0 @@
-
-SDL_image 3.0
-
-The latest version of this library is available from GitHub:
-https://github.com/libsdl-org/SDL_image/releases
-
-This is a simple library to load images of various formats as SDL surfaces.
-It can load BMP, GIF, JPEG, LBM, PCX, PNG, PNM (PPM/PGM/PBM), QOI, TGA, XCF, XPM, and simple SVG format images. It can also load AVIF, JPEG-XL, TIFF, and WebP images, depending on build options (see the note below for details.)
-
-API:
-#include <SDL3_image/SDL_image.h>
-
- SDL_Surface *IMG_Load(const char *file);
-or
- SDL_Surface *IMG_Load_IO(SDL_IOStream *src, SDL_bool closeio);
-or
- SDL_Surface *IMG_LoadTyped_IO(SDL_IOStream *src, SDL_bool closeio, char *type);
-
-where type is a string specifying the format (i.e. "PNG" or "pcx").
-Note that IMG_Load_IO cannot load TGA images.
-
-To create a surface from an XPM image included in C source, use:
-
- SDL_Surface *IMG_ReadXPMFromArray(char **xpm);
-
-An example program 'showimage' is included, with source in examples/showimage.c
-
-Documentation is also available online at https://wiki.libsdl.org/SDL3_image
-
-This library is under the zlib License, see the file "LICENSE.txt" for details.
-
-Note:
-Support for AVIF, JPEG-XL, TIFF, and WebP are not included by default because of the size of the decode libraries, but you can get them by running external/download.sh
-- When building with CMake, you can enable the appropriate SDLIMAGE_* options defined in CMakeLists.txt. SDLIMAGE_VENDORED allows switching between system and vendored libraries.
-- When building with configure/make, you can build and install them normally and the configure script will detect and use them.
-- When building with Visual Studio, you will need to build the libraries and then add the appropriate LOAD_* preprocessor define to the Visual Studio project.
-- When building with Xcode, you can edit the config at the top of the project to enable them, and you will need to include the appropriate framework in your application.
-- For Android, you can edit the config at the top of Android.mk to enable them.
diff --git a/build-scripts/pkg-support/android/README.md.in b/build-scripts/pkg-support/android/INSTALL.md.in
similarity index 61%
rename from build-scripts/pkg-support/android/README.md.in
rename to build-scripts/pkg-support/android/INSTALL.md.in
index 10cbd4e3c..68a11930e 100644
--- a/build-scripts/pkg-support/android/README.md.in
+++ b/build-scripts/pkg-support/android/INSTALL.md.in
@@ -1,77 +1,85 @@
-
-The Simple DirectMedia Layer (SDL for short) is a cross-platform library
-designed to make it easy to write multi-media software, such as games
-and emulators.
-
-The Simple DirectMedia Layer library source code is available from:
-https://www.libsdl.org/
-
-This library is distributed under the terms of the zlib license:
-http://www.zlib.net/zlib_license.html
-
-# @<@PROJECT_NAME@>@-@<@PROJECT_VERSION@>@.aar
-
-This Android archive allows use of @<@PROJECT_NAME@>@ in your Android project, without needing to copy any SDL source.
-
-## Gradle integration
-
-For integration with CMake/ndk-build, it uses [prefab](https://google.github.io/prefab/).
-
-Copy the aar archive (@<@PROJECT_NAME@>@-@<@PROJECT_VERSION@>@.aar) to a `app/libs` directory of your project.
-
-In `app/build.gradle` of your Android project, add:
-```
-android {
- /* ... */
- buildFeatures {
- prefab true
- }
-}
-dependencies {
- implementation files('libs/@<@PROJECT_NAME@>@-@<@PROJECT_VERSION@>@.aar')
- /* ... */
-}
-```
-
-If you're using CMake, add the following to your CMakeLists.txt:
-```
-find_package(@<@PROJECT_NAME@>@ REQUIRED CONFIG)
-target_link_libraries(yourgame PRIVATE @<@PROJECT_NAME@>@::@<@PROJECT_NAME@>@)
-```
-
-If you use ndk-build, add the following before `include $(BUILD_SHARED_LIBRARY)` to your `Android.mk`:
-```
-LOCAL_SHARED_LIBARARIES := @<@PROJECT_NAME@>@
-```
-And add the following at the bottom:
-```
-# https://google.github.io/prefab/build-systems.html
-
-# Add the prefab modules to the import path.
-$(call import-add-path,/out)
-
-# Import @<@PROJECT_NAME@>@ so we can depend on it.
-$(call import-module,prefab/@<@PROJECT_NAME@>@)
-```
-
----
-
-## Other build systems (advanced)
-
-If you want to build a project without Gradle,
-running the following command will extract the Android archive into a more common directory structure.
-```
-python @<@PROJECT_NAME@>@-@<@PROJECT_VERSION@>@.aar -o android_prefix
-```
-Add `--help` for a list of all available options.
-
-
-Look at the example programs in ./examples (of the source archive), and check out online documentation:
- https://wiki.libsdl.org/SDL3/FrontPage
-
-Join the SDL discourse server if you want to join the community:
- https://discourse.libsdl.org/
-
-
-That's it!
-Sam Lantinga <slouken@libsdl.org>
+
+# Using this package
+
+This package contains @<@PROJECT_NAME@>@ built for the Android platform.
+
+## Gradle integration
+
+For integration with CMake/ndk-build, it uses [prefab](https://google.github.io/prefab/).
+
+Copy the aar archive (@<@PROJECT_NAME@>@-@<@PROJECT_VERSION@>@.aar) to a `app/libs` directory of your project.
+
+In `app/build.gradle` of your Android project, add:
+```
+android {
+ /* ... */
+ buildFeatures {
+ prefab true
+ }
+}
+dependencies {
+ implementation files('libs/@<@PROJECT_NAME@>@-@<@PROJECT_VERSION@>@.aar')
+ /* ... */
+}
+```
+
+If you're using CMake, add the following to your CMakeLists.txt:
+```
+find_package(@<@PROJECT_NAME@>@ REQUIRED CONFIG)
+target_link_libraries(yourgame PRIVATE @<@PROJECT_NAME@>@::@<@PROJECT_NAME@>@)
+```
+
+If you use ndk-build, add the following before `include $(BUILD_SHARED_LIBRARY)` to your `Android.mk`:
+```
+LOCAL_SHARED_LIBARARIES := @<@PROJECT_NAME@>@
+```
+And add the following at the bottom:
+```
+# https://google.github.io/prefab/build-systems.html
+
+# Add the prefab modules to the import path.
+$(call import-add-path,/out)
+
+# Import @<@PROJECT_NAME@>@ so we can depend on it.
+$(call import-module,prefab/@<@PROJECT_NAME@>@)
+```
+
+---
+
+## Other build systems (advanced)
+
+If you want to build a project without Gradle,
+running the following command will extract the Android archive into a more common directory structure.
+```
+python @<@PROJECT_NAME@>@-@<@PROJECT_VERSION@>@.aar -o android_prefix
+```
+Add `--help` for a list of all available options.
+
+# Documentation
+
+An API reference and additional documentation is available at:
+
+https://wiki.libsdl.org/@<@PROJECT_NAME@>@
+
+# Discussions
+
+## Discord
+
+You can join the official Discord server at:
+
+https://discord.com/invite/BwpFGBWsv8
+
+## Forums/mailing lists
+
+You can join SDL development discussions at:
+
+https://discourse.libsdl.org/
+
+Once you sign up, you can use the forum through the website or as a mailing list from your email client.
+
+## Announcement list
+
+You can sign up for the low traffic announcement list at:
+
+https://www.libsdl.org/mailing-list.php
+
diff --git a/build-scripts/pkg-support/mingw/INSTALL.md.in b/build-scripts/pkg-support/mingw/INSTALL.md.in
new file mode 100644
index 000000000..b5621a8e2
--- /dev/null
+++ b/build-scripts/pkg-support/mingw/INSTALL.md.in
@@ -0,0 +1,48 @@
+
+# Using this package
+
+This package contains @<@PROJECT_NAME@>@ built for the mingw-w64 toolchain.
+
+The files for 32-bit architecture are in i686-w64-mingw32
+The files for 64-bit architecture are in x86_64-w64-mingw32
+
+You can install them to another location, just type `make` for help.
+
+To use this package, install the latest SDL3 package, point your include path at _arch_/include and your library path at _arch_/lib, link with the @<@PROJECT_NAME@>@ library and copy _arch_/bin/@<@PROJECT_NAME@>@.dll next to your executable.
+
+e.g.
+```sh
+gcc -o hello.exe hello.c -Ix86_64-w64-mingw32/include -Lx86_64-w64-mingw32/lib -l@<@PROJECT_NAME@>@ -lSDL3
+cp x86_64-w64-mingw32/bin/@<@PROJECT_NAME@>@.dll .
+cp _SDL3_INSTALL_PATH_/bin/SDL3.dll .
+./hello.exe
+```
+
+# Documentation
+
+An API reference and additional documentation is available at:
+
+https://wiki.libsdl.org/@<@PROJECT_NAME@>@
+
+# Discussions
+
+## Discord
+
+You can join the official Discord server at:
+
+https://discord.com/invite/BwpFGBWsv8
+
+## Forums/mailing lists
+
+You can join SDL development discussions at:
+
+https://discourse.libsdl.org/
+
+Once you sign up, you can use the forum through the website or as a mailing list from your email client.
+
+## Announcement list
+
+You can sign up for the low traffic announcement list at:
+
+https://www.libsdl.org/mailing-list.php
+
diff --git a/build-scripts/pkg-support/msvc/INSTALL.md.in b/build-scripts/pkg-support/msvc/INSTALL.md.in
new file mode 100644
index 000000000..c0c8e4c6f
--- /dev/null
+++ b/build-scripts/pkg-support/msvc/INSTALL.md.in
@@ -0,0 +1,39 @@
+
+# Using this package
+
+This package contains @<@PROJECT_NAME@>@ built for Visual Studio.
+
+To use this package, edit your project properties:
+- Add the include directory to "VC++ Directories" -> "Include Directories"
+- Add the lib/_arch_ directory to "VC++ Directories" -> "Library Directories"
+- Add @<@PROJECT_NAME@>@.lib to Linker -> Input -> "Additional Dependencies"
+- Copy lib/_arch_/@<@PROJECT_NAME@>@.dll to your project directory.
+
+# Documentation
+
+An API reference and additional documentation is available at:
+
+https://wiki.libsdl.org/@<@PROJECT_NAME@>@
+
+# Discussions
+
+## Discord
+
+You can join the official Discord server at:
+
+https://discord.com/invite/BwpFGBWsv8
+
+## Forums/mailing lists
+
+You can join SDL development discussions at:
+
+https://discourse.libsdl.org/
+
+Once you sign up, you can use the forum through the website or as a mailing list from your email client.
+
+## Announcement list
+
+You can sign up for the low traffic announcement list at:
+
+https://www.libsdl.org/mailing-list.php
+
diff --git a/build-scripts/pkg-support/msvc/arm64/INSTALL.md.in b/build-scripts/pkg-support/msvc/arm64/INSTALL.md.in
new file mode 100644
index 000000000..c185171a3
--- /dev/null
+++ b/build-scripts/pkg-support/msvc/arm64/INSTALL.md.in
@@ -0,0 +1,13 @@
+
+# Using this package
+
+This package contains @<@PROJECT_NAME@>@ built for arm64 Windows.
+
+To use this package, simply replace an existing 64-bit ARM @<@PROJECT_NAME@>@.dll with the one included here.
+
+# Development packages
+
+If you're looking for packages with headers and libraries, you can download one of these:
+- @<@PROJECT_NAME@>@-devel-@<@PROJECT_VERSION@>@-VC.zip, for development using Visual Studio
+- @<@PROJECT_NAME@>@-devel-@<@PROJECT_VERSION@>@-mingw.zip, for development using mingw-w64
+
diff --git a/build-scripts/pkg-support/msvc/x64/INSTALL.md.in b/build-scripts/pkg-support/msvc/x64/INSTALL.md.in
new file mode 100644
index 000000000..74cd67856
--- /dev/null
+++ b/build-scripts/pkg-support/msvc/x64/INSTALL.md.in
@@ -0,0 +1,13 @@
+
+# Using this package
+
+This package contains @<@PROJECT_NAME@>@ built for x64 Windows.
+
+To use this package, simply replace an existing 64-bit @<@PROJECT_NAME@>@.dll with the one included here.
+
+# Development packages
+
+If you're looking for packages with headers and libraries, you can download one of these:
+- @<@PROJECT_NAME@>@-devel-@<@PROJECT_VERSION@>@-VC.zip, for development using Visual Studio
+- @<@PROJECT_NAME@>@-devel-@<@PROJECT_VERSION@>@-mingw.zip, for development using mingw-w64
+
diff --git a/build-scripts/pkg-support/msvc/x86/INSTALL.md.in b/build-scripts/pkg-support/msvc/x86/INSTALL.md.in
new file mode 100644
index 000000000..041c11631
--- /dev/null
+++ b/build-scripts/pkg-support/msvc/x86/INSTALL.md.in
@@ -0,0 +1,13 @@
+
+# Using this package
+
+This package contains @<@PROJECT_NAME@>@ built for x86 Windows.
+
+To use this package, simply replace an existing 32-bit @<@PROJECT_NAME@>@.dll with the one included here.
+
+# Development packages
+
+If you're looking for packages with headers and libraries, you can download one of these:
+- @<@PROJECT_NAME@>@-devel-@<@PROJECT_VERSION@>@-VC.zip, for development using Visual Studio
+- @<@PROJECT_NAME@>@-devel-@<@PROJECT_VERSION@>@-mingw.zip, for development using mingw-w64
+
diff --git a/build-scripts/release-info.json b/build-scripts/release-info.json
index cd307438a..fa27762f0 100644
--- a/build-scripts/release-info.json
+++ b/build-scripts/release-info.json
@@ -62,10 +62,11 @@
},
"files": {
"": [
- "CHANGES.txt",
+ "build-scripts/pkg-support/mingw/INSTALL.md.in:INSTALL.md",
+ "build-scripts/pkg-support/mingw/Makefile",
"LICENSE.txt",
- "README.txt",
- "build-scripts/pkg-support/mingw/Makefile"
+ "README.md"
+ "CHANGES.txt",
],
"cmake": [
"build-scripts/pkg-support/mingw/cmake/SDL3_imageConfig.cmake",
@@ -195,14 +196,17 @@
},
"files-lib": {
"": [
- "README.txt"
+ "build-scripts/pkg-support/msvc/@<@ARCH@>@/INSTALL.md.in:INSTALL.md",
+ "LICENSE.txt",
+ "README.md"
]
},
"files-devel": {
"": [
- "CHANGES.txt",
+ "build-scripts/pkg-support/msvc/INSTALL.md.in:INSTALL.md",
"LICENSE.txt",
- "README.txt"
+ "README.md"
+ "CHANGES.txt",
],
"cmake": [
"build-scripts/pkg-support/msvc/cmake/SDL3_imageConfig.cmake.in:SDL3_imageConfig.cmake",
@@ -274,8 +278,8 @@
"x86",
"x86_64"
],
- "api-minimum": 19,
- "api-target": 29,
+ "api-minimum": 21,
+ "api-target": 35,
"ndk-minimum": 21,
"aar-files": {
"": [
@@ -293,7 +297,9 @@
},
"files": {
"": [
- "build-scripts/pkg-support/android/README.md.in:README.md"
+ "build-scripts/pkg-support/android/INSTALL.md.in:INSTALL.md",
+ "LICENSE.txt",
+ "README.md"
]
},
"dependencies": {
diff --git a/docs/INTRO-androidstudio.md b/docs/INTRO-androidstudio.md
new file mode 100644
index 000000000..a43e74f7e
--- /dev/null
+++ b/docs/INTRO-androidstudio.md
@@ -0,0 +1,8 @@
+
+# Introduction to SDL with Android Studio
+
+A complete example is available at:
+
+https://github.com/Ravbug/sdl3-sample
+
+Support for AVIF, JPEG-XL, TIFF, and WebP are not included by default because of the size of the decode libraries, but you can get them by running external/download.sh and then editing the config at the top of Android.mk to enable them.
diff --git a/docs/INTRO-cmake.md b/docs/INTRO-cmake.md
new file mode 100644
index 000000000..7504acf68
--- /dev/null
+++ b/docs/INTRO-cmake.md
@@ -0,0 +1,59 @@
+
+# Introduction to SDL with CMake
+
+The easiest way to use SDL is to include it as a subproject in your project.
+
+We'll start by creating a simple project to build and run [hello.c](hello.c)
+
+Create the file CMakeLists.txt
+```cmake
+cmake_minimum_required(VERSION 3.16)
+project(hello)
+
+# Enable Objective C on Apple platforms, for ImageIO support
+if(APPLE)
+ enable_language(OBJC)
+endif()
+
+# set the output directory for built objects.
+# This makes sure that the dynamic library goes into the build directory automatically.
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/$<CONFIGURATION>")
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/$<CONFIGURATION>")
+
+# This assumes the SDL source is available in vendored/SDL
+add_subdirectory(vendored/SDL EXCLUDE_FROM_ALL)
+
+# This assumes the SDL_image source is available in vendored/SDL_image
+add_subdirectory(vendored/SDL_image EXCLUDE_FROM_ALL)
+
+# Create your game executable target as usual
+add_executable(hello WIN32 hello.c)
+
+# Link to the actual SDL3 library.
+target_link_libraries(hello PRIVATE SDL3::SDL3 SDL3_image::SDL3_image)
+```
+
+Build:
+```sh
+cmake -S . -B build
+cmake --build build
+```
+
+Run:
+- On Windows the executable is in the build Debug directory:
+```sh
+cd build/Debug
+./hello
+```
+- On other platforms the executable is in the build directory:
+```sh
+cd build
+./hello
+```
+
+Support for AVIF, JPEG-XL, TIFF, and WebP are not included by default because of the size of the decode libraries, but you can get them by running the external/download.sh script and then enabling the appropriate SDLIMAGE_* options defined in CMakeLists.txt. SDLIMAGE_VENDORED allows switching between system and vendored libraries.
+
+A more complete example is available at:
+
+https://github.com/Ravbug/sdl3-sample
+
diff --git a/docs/INTRO-emscripten.md b/docs/INTRO-emscripten.md
new file mode 100644
index 000000000..52674b39d
--- /dev/null
+++ b/docs/INTRO-emscripten.md
@@ -0,0 +1,37 @@
+
+# Introduction to SDL with Emscripten
+
+First, you should have the Emscripten SDK installed from:
+
+https://emscripten.org/docs/getting_started/downloads.html
+
+We'll start by creating a simple project to build and run [hello.c](hello.c)
+
+## Building SDL_image
+
+Once you have a command line interface with the Emscripten SDK set up and you've changed directory to the SDL_image directory, you can build SDL_image like this:
+
+```sh
+mkdir hello
+cd hello
+emcmake cmake ..
+emmake make
+```
+
+## Building your app
+
+In this case we'll just run a simple command to compile our source with the SDL library we just built:
+```sh
+emcc -o index.html ../docs/hello.c -I../include -L. -lSDL3_image -lSDL3
+```
+
+## Running your app
+
+You can now run your app by pointing a webserver at your build directory and connecting a web browser to it.
+
+## More information
+
+A more complete example is available at:
+
+https://github.com/Ravbug/sdl3-sample
+
diff --git a/docs/INTRO-visualstudio.md b/docs/INTRO-visualstudio.md
new file mode 100644
index 000000000..946bacb40
--- /dev/null
+++ b/docs/INTRO-visualstudio.md
@@ -0,0 +1,17 @@
+
+# Introduction to SDL_image with Visual Studio
+
+The easiest way to use SDL_image is to include it as a subproject in your project.
+
+We'll start by creating a simple project to build and run [hello.c](hello.c)
+
+- Create a new project in Visual Studio, using the C++ Empty Project template
+- Add hello.c to the Source Files
+- Right click the solution, select add an existing project, navigate to SDL VisualC/SDL and add SDL.vcxproj
+- Right click the solution, select add an existing project, navigate to SDL_image VisualC and add SDL_image.vcxproj
+- Select your main project and go to Project -> Project Dependencies and select SDL3
+- Select your main project and go to Project -> Properties, set the filter at the top to "All Configurations" and "All Platforms", select VC++ Directories and add the SDL include directory to "Include Directories"
+- Select your main project and go to Project -> Add Reference and select SDL3 and SDL3_image
+- Build and run!
+
+Support for AVIF, JPEG-XL, TIFF, and WebP are not included by default because of the size of the decode libraries, but you can get them by running external/download.sh, and then building the libraries and adding the appropriate LOAD_* preprocessor define to the SDL_image Visual Studio project.
diff --git a/docs/INTRO-xcode.md b/docs/INTRO-xcode.md
new file mode 100644
index 000000000..e8075bff3
--- /dev/null
+++ b/docs/INTRO-xcode.md
@@ -0,0 +1,19 @@
+
+# Introduction to SDL_image with Xcode
+
+The easiest way to use SDL_image is to include it as a subproject in your project.
+
+We'll start by creating a simple project to build and run [hello.c](hello.c)
+
+- Create a new project in Xcode, using the App template and selecting Objective C as the language
+- Remove the .h and .m files that were automatically added to the project
+- Remove the main storyboard that was automatically added to the project
+- On iOS projects, select the project, select the main target, select the Info tab, look for "Custom iOS Target Properties", and remove "Main storyboard base file name" and "Application Scene Manifest"
+- Right click the project and select "Add Files to [project]", navigate to the SDL_image docs directory and add the file hello.c
+- Right click the project and select "Add Files to [project]", navigate to the SDL Xcode/SDL directory and add SDL.xcodeproj
+- Right click the project and select "Add Files to [project]", navigate to the SDL_image Xcode directory and add SDL_image.xcodeproj
+- Select the project, select the main target, select the General tab, look for "Frameworks, Libaries, and Embedded Content", and add SDL3.framework and SDL3_image.framework
+- Build and run!
+
+Support for AVIF, JPEG-XL, TIFF, and WebP are not included by default because of the size of the decode libraries, but you can get them by running external/download.sh and editing the config at the top of the Xcode project to enable them. You will need to include the appropriate framework in your application.
+
diff --git a/docs/README-emscripten.txt b/docs/README-emscripten.txt
deleted file mode 100644
index 8642ebe70..000000000
--- a/docs/README-emscripten.txt
+++ /dev/null
@@ -1,20 +0,0 @@
-Building SDL3_image
--------------------
-
-The easiest way to use SDL3_image with Emscripten is to use Emscripten ports (https://kripken.github.io/emscripten-site/docs/compiling/Building-Projects.html#emscripten-ports) (-s USE_SDL_IMAGE=2).
-
-If you want to build it yourself instead you can use these instructions:
-
-Step 0 - get emscripten
-
-Step 1 - get sdl3-emscripten
- * clone https://github.com/emscripten-ports/SDL3.git
- * follow the build instructions in SDL3/docs/README-emscripten.md (make sure to pass a --prefix to configure)
- * make install
-
-Step 2 - get sdl_image
- * emconfigure ./configure --disable-sdltest --with-sdl-prefix=/path/to/sdl --prefix=/path/to/install
- * (where /path/to/sdl is the path you passed as --prefix to SDL3 configure)
- * emmake make
- * make install
-
diff --git a/docs/hello.c b/docs/hello.c
new file mode 100644
index 000000000..cebf47e78
--- /dev/null
+++ b/docs/hello.c
@@ -0,0 +1,130 @@
+/*
+ Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
+
+ This software is provided 'as-is', without any express or implied
+ warranty. In no event will the authors be held liable for any damages
+ arising from the use of this software.
+
+ Permission is granted to anyone to use this software for any purpose,
+ including commercial applications, and to alter it and redistribute it
+ freely.
+*/
+#define SDL_MAIN_USE_CALLBACKS 1 /* use the callbacks instead of main() */
+#include <SDL3/SDL.h>
+#include <SDL3/SDL_main.h>
+#include <SDL3_image/SDL_image.h>
+
+static unsigned char icon_bmp[] = {
+ 0x42, 0x4d, 0x42, 0x02, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x42, 0x00,
+ 0x00, 0x00, 0x28, 0x00, 0x00, 0x00, 0x20, 0x00, 0x00, 0x00, 0x20, 0x00,
+ 0x00, 0x00, 0x01, 0x00, 0x04, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02,
+ 0x00, 0x00, 0x6d, 0x0b, 0x00, 0x00, 0x6d, 0x0b, 0x00, 0x00, 0x03, 0x00,
+ 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x11, 0x11, 0x11, 0x11, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x11, 0x22, 0x22, 0x22, 0x22,
+ 0x11, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x22,
+ 0x21, 0x11, 0x11, 0x12, 0x22, 0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x12, 0x21, 0x11, 0x11, 0x11, 0x11, 0x12, 0x21, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x22, 0x11, 0x11, 0x11, 0x11, 0x11,
+ 0x11, 0x22, 0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x12, 0x21, 0x11,
+ 0x22, 0x22, 0x22, 0x22, 0x11, 0x12, 0x21, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x12, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x21, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x01, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22,
+ 0x22, 0x22, 0x22, 0x10, 0x00, 0x00, 0x00, 0x00, 0x01, 0x22, 0x22, 0x22,
+ 0x22, 0x21, 0x12, 0x22, 0x22, 0x22, 0x22, 0x10, 0x00, 0x00, 0x00, 0x00,
+ 0x01, 0x22, 0x22, 0x22, 0x22, 0x21, 0x12, 0x22, 0x22, 0x22, 0x22, 0x10,
+ 0x00, 0x00, 0x00, 0x00, 0x01, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22,
+ 0x22, 0x22, 0x22, 0x10, 0x00, 0x00, 0x00, 0x00, 0x01, 0x22, 0x22, 0x22,
+ 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x10, 0x00, 0x00, 0x00, 0x00,
+ 0x01, 0x22, 0x22, 0x11, 0x11, 0x22, 0x22, 0x11, 0x11, 0x22, 0x22, 0x10,
+ 0x00, 0x00, 0x00, 0x00, 0x01, 0x22, 0x22, 0x11, 0x01, 0x22, 0x22, 0x11,
+ 0x01, 0x22, 0x22, 0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x12, 0x22, 0x11,
+ 0x11, 0x22, 0x22, 0x11, 0x11, 0x22, 0x21, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x12, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x21, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22,
+ 0x22, 0x22, 0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x12, 0x22,
+ 0x22, 0x22, 0x22, 0x22, 0x22, 0x21, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x01, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x10, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x11, 0x22, 0x22, 0x22, 0x22,
+ 0x11, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x11, 0x11, 0x11, 0x11, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00
+};
+static unsigned int icon_bmp_len = 578;
+
+static SDL_Window *window = NULL;
+static SDL_Renderer *renderer = NULL;
+static SDL_Texture *texture = NULL;
+
+/* This function runs once at startup. */
+SDL_AppResult SDL_AppInit(void **appstate, int argc, char *argv[])
+{
+ /* Create the window */
+ if (!SDL_CreateWindowAndRenderer("Hello World", 800, 600, SDL_WINDOW_FULLSCREEN, &window, &renderer)) {
+ SDL_Log("Couldn't create window and renderer: %s\n", SDL_GetError());
+ return SDL_APP_FAILURE;
+ }
+
+ /* Load the icon */
+ texture = IMG_LoadTexture_IO(renderer, SDL_IOFromConstMem(icon_bmp, icon_bmp_len), true);
+ if (!texture) {
+ SDL_Log("Couldn't load icon: %s\n", SDL_GetError());
+ return SDL_APP_FAILURE;
+ }
+
+ return SDL_APP_CONTINUE;
+}
+
+/* This function runs when a new event (mouse input, keypresses, etc) occurs. */
+SDL_AppRes
(Patch may be truncated, please check the link at the top of this post.)