You are looking at historical revision 32855 of this page. It may differ significantly from its current revision.
sdl2-image
Introduction
The sdl2-image egg provides bindings to SDL_image version 2. SDL_image is a library for loading various image formats, compatible with 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 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
- BSD 2-Clause
Requirements
The sdl2-image egg requires the sdl2 egg, Simple DirectMedia Layer version 2.0.0 or higher, and SDL_image version 2.0 or higher. It will not work with older versions of SDL or SDL_image.
Installation
ATTENTION: The sdl2-image egg has not been released yet. For now, you must download it from its source code repository and follow the instructions in the README.
When installing the egg, you should set the SDL2_FLAGS environment variable to a string of compiler flags to be used when compiling the egg. If you have the sdl2-config helper program installed on your system, you can set appropriate flags and install the extension like so (notice these are back ticks, not quotes):
export SDL2_FLAGS=`sdl2-config --cflags --libs` chicken-install sdl2-image
If you do not have the sdl2-config helper program installed on your computer, you may manually specify SDL-related compiler flags (notice these are double quotes, not back ticks):
export SDL2_FLAGS="-I/usr/local/include/SDL2 -L/usr/local/lib -lSDL2" chicken-install sdl2-image
By default, the sdl2-image egg will be linked against SDL_image using the compiler flag -lSDL2_image. You can override this by setting the SDL2_IMAGE_FLAGS environment variable, if needed. You can also use that environment variable in case you have installed SDL_image in a different location than SDL.
The SDL2_FLAGS and SDL2_IMAGE_FLAGS environment variables are only needed during installation of the egg. They do not need to be set during normal use.
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:
(use (prefix sdl2-image img:)) (img:load "image.jpg")
The chicken-sdl2-examples repository contains complete example games and programs, some of which use the sdl2-image egg.
Version History
The sdl2-image egg has not yet been released. Coming soon!
API
Quick Start
;; Import sdl2, sdl2-image, and srfi-4 (only needed for u8vectors): (use (prefix sdl2 sdl2:) (prefix sdl2-image img:) srfi-4) ;; Load an image from a file: (img:load "path/to/my-image.jpg") ;; or png, gif, etc. ;; Load an image from a string containing image data: (let ((source "...")) (img:load-rw (sdl2:rw-from-string ))) ;; Load an image from a blob containing image data: (let ((source '#${...})) (img:load-rw (sdl2:rw-from-blob source))) ;; Load an image from a SRFI-4 u8vector containing image data: (let ((source '#u8(...))) (img:load-rw (sdl2:rw-from-u8vector source)))
Conventions
- Procedure names are lower case and hyphenated, with no "IMG_" prefix.
- Procedures that cause a side effect are suffixed with "!".
- The loading procedures have two versions, one without an asterisk and one with an asterisk, e.g. load and load*.
- The procedure without an asterisk returns a record whose underlying struct will be automatically freed when the record is garbage collected. (This is accomplished using set-finalizer!.) Unless you have a good reason to do manual memory management, you should use this procedure, not the procedure with an asterisk.
- The procedure with an asterisk returns a record that must be manually freed when you are done with it, using free-surface! from the sdl2 egg. This is slightly more efficient, especially if you are allocating hundreds or thousands of objects, but your program will leak memory if you forget to free it.
General
[procedure] (init! #!optional loaders) → list of symbolsSee 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, including any that were already 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 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.
[procedure] (quit!)See IMG_Quit.
[procedure] (linked-version) → sdl2:versionSee IMG_LinkedVersion.
Returns an sdl2:version instance containing the version number of SDL_image that the sdl2-image egg is currently using. (This may be different than the version it was compiled with.)
[procedure] (compiled-version) → sdl2:versionSee SDL_IMAGE_VERSION.
Returns an sdl2:version instance containing the version number of SDL_image that the sdl2-image egg was compiled with. (This may be different than the version it is currently using.)
Loading
[procedure] (load filepath) → sdl2:surface or #fSee IMG_Load.
Attempts to load the image file at the given filepath (a string). The file may be any image format supported by SDL_image.
Returns #f if the image could not be loaded. Call get-error (from the sdl2 egg) to find out what the problem is.
[procedure] (load* filepath) → sdl2:surface or #fLike load, except that the sdl2:surface will not have a finalizer. You must call free-surface! (from the sdl2 egg) when you are done with the sdl2:surface.
[procedure] (load-rw rwops #!optional close?) → sdl2:surface or #fSee IMG_Load_RW.
Load an image from a sdl2:rwops. This procedure allows you to load an image from a variety of sources, such as a string, blob, u8vector, memory pointer, or file.
If close? is #t, the sdl2:rwops will be automatically closed after the image is loaded. If close? is #f, the sdl2:rwops will not be closed.
Returns #f if the image could not be loaded. Call get-error (from the sdl2 egg) to find out what the problem is.
If you want to load a TGA image from a sdl2:rwops, you will probably need to use load-typed-rw instead of load-rw.
[procedure] (load-rw* rwops #!optional close?) → sdl2:surface or #fLike load-rw, except that the sdl2:surface will not have a finalizer. You must call free-surface! (from the sdl2 egg) when you are done with the sdl2:surface.
[procedure] (load-typed-rw rwops close? type-hint) → sdl2:surface or #fSee IMG_LoadTyped_RW.
Like load-rw, except you can give a hint to help SDL_image figure out what image format it is. In practice, the hint is only necessary when loading TGA images. For all other image formats you can 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 #f if the image could not be loaded. Call get-error (from the sdl2 egg) to find out what the problem is.
[procedure] (load-typed-rw* rwops close? type) → sdl2:surface or #fLike load-typed-rw, except that the sdl2:surface will not have a finalizer. You must call free-surface! (from the sdl2 egg) when you are done with the sdl2:surface.
Returns #f if the image could not be loaded. Call get-error (from the sdl2 egg) to find out what the problem is.