This file contains an archive of the sdl2-image egg wiki page. The most up-to-date version of these docs is available at: http://wiki.call-cc.org/eggref/5/sdl2-image == sdl2-image The sdl2-image egg provides bindings to [[http://www.libsdl.org/projects/SDL_image/|SDL_image]] version 2. SDL_image is a library for loading various image formats, compatible with [[http://libsdl.org/|Simple DirectMedia Layer]] version 2 (SDL2), a popular library used in games and other media-rich software. The sdl2-image egg is designed to be compatible with the [[/egg/sdl2|sdl2]] egg, which provides bindings to SDL 2 itself. ; Project / Source Code Repository : [[https://gitlab.com/chicken-sdl2/chicken-sdl2-image]] ; Issue Tracker : [[https://gitlab.com/chicken-sdl2/chicken-sdl2-image/issues]] ; Maintainer : John Croisant (john+chicken at croisant dot net) ; License: [[https://gitlab.com/chicken-sdl2/chicken-sdl2-image/blob/master/LICENSE-BSD.txt|BSD 2-Clause]] '''Table of Contents:''' [[toc:]] == Requirements The sdl2-image egg requires the [[/egg/sdl2|sdl2]] egg, [[http://libsdl.org/|Simple DirectMedia Layer]] 2.0.0 or higher, and [[http://www.libsdl.org/projects/SDL_image/|SDL_image]] 2.0 or higher. It will not work with older versions of SDL or SDL_image. This egg requires CHICKEN Scheme 4.8 or higher. As of version 0.2.0, this egg is compatible with both CHICKEN 4 and CHICKEN 5. == Installation In most cases, you can install the sdl2-image egg in the usual way: chicken-install sdl2-image The installer will try to automatically determine the SDL2 compiler and linker flags using the {{sdl2-config}} command. In special cases, you may need to set the {{SDL2_CFLAGS}}, {{SDL2_LDFLAGS}}, {{SDL2_IMAGE_CFLAGS}}, and/or {{SDL2_IMAGE_LDFLAGS}} environment variables to provide the compiler and linker flags, then try again. (The {{SDL2_IMAGE_*}} flags are used in addition to the {{SDL2_*}} flags.) For example: export SDL2_CFLAGS="-I/usr/local/include/SDL2" export SDL2_LDFLAGS="-L/usr/local/lib -lSDL2" export SDL2_IMAGE_LDFLAGS="-lSDL2_image" chicken-install sdl2-image These environment variables are needed only when installing the egg itself. They are not needed when compiling or running programs that use the egg. === Installing on macOS On macOS, the sdl2-image egg can be compiled using either UNIX-style libraries (e.g. compiled from source or installed via Homebrew) or Mac-style frameworks (e.g. downloaded from the SDL website). When automatically determining compiler and linker flags on macOS, the installer will first check to see if {{sdl2-config}} is available. If it is available, the installer will use it to determine the flags. If {{sdl2-config}} is not available, the installer will check to see if {{SDL2.framework}} and {{SDL2_image.framework}} are available in either the {{/Library/Frameworks}} or {{/System/Library/Frameworks}} directories. If so, the installer will use the frameworks. If the frameworks are installed in some other directory, or if you want to force using the framework even when {{sdl2-config}} is available, set the {{SDL2_CFLAGS}}, {{SDL2_LDFLAGS}}, {{SDL2_IMAGE_CFLAGS}}, and/or {{SDL2_IMAGE_LDFLAGS}} enviroment variables to tell the compiler where to find the frameworks: export SDL2_CFLAGS="-F/path/to/your/frameworks" export SDL2_LDFLAGS="-F/path/to/your/frameworks -framework SDL2" export SDL2_IMAGE_LDFLAGS="-framework SDL2_image" chicken-install sdl2 == Usage and Examples To avoid procedure name collisions, it is recommended that you import the sdl2-image module using a prefix such as "img:", like so: (cond-expand (chicken-4 (use (prefix sdl2 "sdl2:") (prefix sdl2-image "img:"))) (chicken-5 (import (prefix sdl2 "sdl2:") (prefix sdl2-image "img:")))) (img:load "image.jpg") The [[https://gitlab.com/chicken-sdl2/chicken-sdl2-examples|chicken-sdl2-examples repository]] contains complete example games and programs, some of which use the sdl2-image egg. == Version History ; 0.2.0 (2019-02-13) : Ported to be compatible with both CHICKEN 4 and CHICKEN 5. More user-friendly installation process. ; 0.1.0 (2015-12-19) : Initial release. For more information about what changed in each version, see the [[https://gitlab.com/chicken-sdl2/chicken-sdl2-image/blob/master/CHANGELOG.md|CHANGELOG]]. == API === Quick Start (cond-expand (chicken-4 (use (prefix sdl2 "sdl2:") (prefix sdl2-image "img:") (only lolevel object-evict object-release))) (chicken-5 (import (prefix sdl2 "sdl2:") (prefix sdl2-image "img:") object-evict))) ;; Load an image from a file. (img:load "path/to/my-image.jpg") ;; or png, gif, etc. ;; Load an image from a blob containing image data. ;; The blob is evicted to static memory so that it will ;; not be moved in memory by the garbage collector. (let* ((source (object-evict '#${...})) (rwops (sdl2:rw-from-blob source)) (surf (img:load-rw rwops #t))) (object-release source) surf) ;; Load an image from a string containing image data. ;; Like above, the string is evicted. (let* ((source (object-evict "...")) (rwops (sdl2:rw-from-string source)) (surf (img:load-rw rwops #t))) (object-release source) surf) === About the API ==== API Stability The sdl2-image egg follows "[[http://semver.org/|semantic versioning]]". Until version 1.0.0 is released, the API is not guaranteed to be "stable". That means the maintainer reserves the right to change the API if needed, possibly in ways that break backward compatibility with previous versions. '''Large backward-incompatible changes are unlikely''', but there may be small tweaks and fixes to the API if problems are discovered. After version 1.0.0 is released, the API is guaranteed to remain stable (no backward-incompatible changes) until the next new major version (e.g. going from version 1.x to 2.0.0, or 2.x to 3.0.0). ==== Conventions * Procedure names are lower case and hyphenated, with no "IMG_" prefix. * Procedures that cause a side effect are suffixed with "!". * Some procedures have two versions: one that returns a managed sdl2:surface, and one that returns an unmanaged sdl2:surface. See [[/egg/sdl2#struct-memory-management|Struct Memory Management]] in the sdl2 egg docs. * Procedures signal an exception of kind {{(exn sdl2)}} if they fail. === General (init! #!optional loaders) → list of symbols See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC8|IMG_Init]]. {{loaders}} defaults to {{'(jpg png tif)}}. It must be a list of zero or more of those symbols, indicating which image loaders to initialize. (Other image formats are built into SDL_image and do not need to be initialized.) Returns a list of symbols indicating all the image loaders that are now initialized. You should check the return value to see whether all the image loaders you requested were actually initialized. If not, {{get-error}} from the sdl2 egg ''might'' return an error message explaining why the image loader could not be initialized. (This is a limitation of SDL_image.) It is not usually necessary to call this procedure. Image loaders will automatically be initialized when needed. But, you may wish to call this procedure to check whether a loader is available, or to initialize the loaders ahead of time to avoid a small delay later. (quit!) See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC9|IMG_Quit]]. (compiled-version) → list of fixnums (current-version) → list of fixnums Returns a list of three nonnegative integers, indicating a version number of SDL_image. For example, the list {{(2 0 0)}} indicates SDL_image 2.0.0. * {{compiled-version}} returns the version of SDL_image that the sdl2-image egg was compiled with. * {{current-version}} returns the version of SDL_image that the sdl2-image egg is currently using. For example, the user may have compiled the sdl2-image egg with SDL_image 2.0.1, then later upgraded SDL_image to 2.0.2, but not yet recompiled the sdl2-image egg with the new version. In such a case, {{compiled-version}} would return {{(2 0 1)}}, and {{current-version}} would return {{(2 0 2)}}. But, features from the new version would not be available until the user recompiles the sdl2-image egg. See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC7|SDL_IMAGE_VERSION and IMG_LinkedVersion]]. === Loading (load filepath) → sdl2:surface (load* filepath) → sdl2:surface Attempts to load the image file at the given filepath (a string). The image may be any format supported by SDL_image. See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC11|IMG_Load]]. Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] with the image contents. Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded. * {{load}} returns a managed sdl2:surface. * {{load*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} (from the sdl2 egg) when you are done with it. (load-rw rwops #!optional close?) → sdl2:surface (load-rw* rwops #!optional close?) → sdl2:surface Attempts to load an image from an [[/egg/sdl2#rwops|sdl2:rwops]]. This procedure allows you to load an image from a variety of sources, such as a [[/man/4/Unit library#blobs|blob]], string, memory pointer, or file. See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC12|IMG_Load_RW]]. The image may be any format supported by SDL_image, except TGA. If you want to load a TGA image from an sdl2:rwops, you should use {{load-typed-rw}} instead. If {{close?}} is #t, the sdl2:rwops will be automatically closed after the image is loaded. See {{rw-close!}} in the sdl2 egg. If {{close?}} is #f (the default), the sdl2:rwops will not be closed. Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] with the image contents. Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded. * {{load-rw}} returns a managed sdl2:surface. * {{load-rw*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} (from the sdl2 egg) when you are done with it. (load-typed-rw rwops close? type-hint) → sdl2:surface (load-typed-rw* rwops close? type-hint) → sdl2:surface See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC13|IMG_LoadTyped_RW]]. Similar to {{load-rw}}, except you also give a hint to help SDL_image figure out what the image format is. In practice, this is only necessary when loading a TGA image from an sdl2:rwops. For other image formats you can just use {{load-rw}} instead. {{type-hint}} must be one of the following strings (case is not important): * {{"BMP"}} * {{"CUR"}} * {{"GIF"}} * {{"ICO"}} * {{"JPG"}} * {{"LBM"}} * {{"PCX"}} * {{"PNG"}} * {{"PNM"}} * {{"TGA"}} * {{"TIF"}} * {{"XCF"}} * {{"XPM"}} * {{"XV"}} Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the image. Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded. * {{load-rw-typed}} returns a managed sdl2:surface. * {{load-rw-typed*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} (from the sdl2 egg) when you are done with it.