source: project/wiki/eggref/5/sdl2-image @ 37226

Last change on this file since 37226 was 37226, checked in by jacius, 4 months ago

Move and symlink sdl2-image and sdl2-ttf wiki pages.

File size: 9.9 KB
Line 
1== sdl2-image
2
3The sdl2-image egg provides bindings to
4[[http://www.libsdl.org/projects/SDL_image/|SDL_image]] version 2.
5SDL_image is a library for loading various image formats, compatible
6with [[http://libsdl.org/|Simple DirectMedia Layer]] version 2 (SDL2),
7a popular library used in games and other media-rich software.
8
9The sdl2-image egg is designed to be compatible with the
10[[/egg/sdl2|sdl2]] egg, which provides bindings to SDL 2 itself.
11
12; Project / Source Code Repository : [[https://gitlab.com/chicken-sdl2/chicken-sdl2-image]]
13; Issue Tracker : [[https://gitlab.com/chicken-sdl2/chicken-sdl2-image/issues]]
14; Maintainer : John Croisant (john+chicken at croisant dot net)
15; License: [[https://gitlab.com/chicken-sdl2/chicken-sdl2-image/blob/master/LICENSE-BSD.txt|BSD 2-Clause]]
16
17
18'''Table of Contents:'''
19
20[[toc:]]
21
22
23== Requirements
24
25The sdl2-image egg requires the [[/egg/sdl2|sdl2]] egg,
26[[http://libsdl.org/|Simple DirectMedia Layer]] version 2.0.0 or
27higher, and [[http://www.libsdl.org/projects/SDL_image/|SDL_image]]
28version 2.0 or higher. It will not work with older versions of SDL or
29SDL_image.
30
31This egg requires CHICKEN Scheme 4.8 or higher.
32Please file an issue or contact the maintainer if you need to use this library with an earlier version of CHICKEN Scheme.
33
34
35== Installation
36
37When installing the egg, you should set the {{SDL2_FLAGS}} environment
38variable to a string of compiler flags to be used when compiling the
39egg. If you have the {{sdl2-config}} helper program installed on your
40system, you can set appropriate flags and install the extension like
41so (notice these are back ticks, not quotes):
42
43 export SDL2_FLAGS=`sdl2-config --cflags --libs`
44 chicken-install sdl2-image
45
46If you do not have the {{sdl2-config}} helper program installed on your
47computer, you may manually specify SDL-related compiler flags (notice
48these are double quotes, not back ticks):
49
50 export SDL2_FLAGS="-I/usr/local/include/SDL2 -L/usr/local/lib -lSDL2"
51 chicken-install sdl2-image
52
53By default, the sdl2-image egg will be linked against SDL_image using
54the compiler flag {{-lSDL2_image}}. You can override this by setting the
55{{SDL2_IMAGE_FLAGS}} environment variable, if needed. You can also use
56that environment variable in case you have installed SDL_image in a
57different location than SDL.
58
59The {{SDL2_FLAGS}} and {{SDL2_IMAGE_FLAGS}} environment variables are
60only needed during installation of the egg. They do not need to be set
61during normal use.
62
63
64== Usage and Examples
65
66To avoid procedure name collisions, it is recommended that you import
67the sdl2-image module using a prefix such as "img:", like so:
68
69<enscript highlight="scheme">
70(use (prefix sdl2-image img:))
71(img:load "image.jpg")
72</enscript>
73
74The [[https://gitlab.com/chicken-sdl2/chicken-sdl2-examples|chicken-sdl2-examples repository]]
75contains complete example games and programs, some of which use the sdl2-image egg.
76
77
78== Version History
79
80; 0.1.0 (2015-12-19) : Initial release.
81
82For more information about what changed in each version,
83see the [[https://gitlab.com/chicken-sdl2/chicken-sdl2-image/blob/master/CHANGELOG.md|CHANGELOG]].
84
85
86
87== API
88
89=== Quick Start
90
91<enscript highlight="scheme">
92(use (prefix sdl2 sdl2:)
93     (prefix sdl2-image img:)
94     (only lolevel
95           object-evict object-release))
96
97;; Load an image from a file.
98(img:load "path/to/my-image.jpg") ;; or png, gif, etc.
99
100;; Load an image from a blob containing image data.
101;; The blob is evicted to static memory so that it will
102;; not be moved in memory by the garbage collector.
103(let* ((source (object-evict '#${...}))
104       (rwops (sdl2:rw-from-blob source))
105       (surf (img:load-rw rwops #t)))
106  (object-release source)
107  surf)
108
109;; Load an image from a string containing image data.
110;; Like above, the string is evicted.
111(let* ((source (object-evict "..."))
112       (rwops (sdl2:rw-from-string source))
113       (surf (img:load-rw rwops #t)))
114  (object-release source)
115  surf)
116</enscript>
117
118
119=== About the API
120
121==== API Stability
122
123The sdl2-image egg follows "[[http://semver.org/|semantic versioning]]".
124Until version 1.0.0 is released, the API is not guaranteed to be "stable".
125That means the maintainer reserves the right to change the API if needed,
126possibly in ways that break backwards compatibility with previous versions.
127'''Large backwards-incompatible changes are unlikely''',
128but there may be small tweaks and fixes to the API if problems are discovered.
129
130After version 1.0.0 is released, the API is guaranteed to remain stable (no backwards-incompatible changes)
131until the next new major version (e.g. going from version 1.x to 2.0.0, or 2.x to 3.0.0).
132
133==== Conventions
134
135* Procedure names are lower case and hyphenated, with no "IMG_" prefix.
136
137* Procedures that cause a side effect are suffixed with "!".
138
139* Some procedures have two versions: one that returns a managed sdl2:surface, and one that returns an unmanaged sdl2:surface.
140  See [[/egg/sdl2#struct-memory-management|Struct Memory Management]] in the sdl2 egg docs.
141
142* Procedures signal an exception of kind {{(exn sdl2)}} if they fail.
143
144
145=== General
146
147<procedure>(init! #!optional loaders) → list of symbols</procedure>
148
149See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC8|IMG_Init]].
150
151{{loaders}} defaults to {{'(jpg png tif)}}. It must be a list of zero
152or more of those symbols, indicating which image loaders to
153initialize. (Other image formats are built into SDL_image and do not
154need to be initialized.)
155
156Returns a list of symbols indicating all the image loaders that are
157now initialized, including any that were already initialized. You
158should check the return value to see whether all the image loaders you
159requested were actually initialized. If not, {{get-error}} from the
160sdl2 egg ''might'' return an error message explaining why the image
161loader could not be initialized. (This is a limitation of SDL_image.)
162
163It is not usually necessary to call this procedure. Image loaders will
164automatically be initialized when needed. But, you may wish to call
165this procedure to check whether a loader is available, or to
166initialize the loaders ahead of time to avoid a small delay later.
167
168
169<procedure>(quit!)</procedure>
170
171See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC9|IMG_Quit]].
172
173
174<procedure>(compiled-version) → list of fixnums</procedure>
175<procedure>(current-version)  → list of fixnums</procedure>
176
177Returns a list of three nonnegative integers, indicating a version number of SDL_image.
178For example, the list {{(2 0 0)}} indicates SDL_image 2.0.0.
179
180* {{compiled-version}} returns the version of SDL_image that the sdl2-image egg was compiled with.
181* {{current-version}} returns the version of SDL_image that the sdl2-image egg is currently using.
182
183For example, the user may have compiled the sdl2-image egg with SDL_image 2.0.0, then later upgraded SDL_image to 2.1.0, but not yet recompiled the sdl2-image egg with the new version.
184In such a case, {{compiled-version}} would return {{(2 0 0)}}, and {{current-version}} would return {{(2 1 0)}}.
185But, features from the new version would not be available until the user recompiles the sdl2-image egg.
186
187See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC7|SDL_IMAGE_VERSION and IMG_LinkedVersion]].
188
189
190
191=== Loading
192
193<procedure>(load  filepath) → sdl2:surface</procedure>
194<procedure>(load* filepath) → sdl2:surface</procedure>
195
196Attempts to load the image file at the given filepath (a string).
197The image may be any format supported by SDL_image.
198See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC11|IMG_Load]].
199
200Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] with the image contents.
201Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
202
203* {{load}} returns a managed sdl2:surface.
204* {{load*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} (from the sdl2 egg) when you are done with it.
205
206
207<procedure>(load-rw  rwops #!optional close?) → sdl2:surface</procedure>
208<procedure>(load-rw* rwops #!optional close?) → sdl2:surface</procedure>
209
210Attempts to load an image from an [[/egg/sdl2#rwops|sdl2:rwops]].
211This 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.
212See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC12|IMG_Load_RW]].
213
214The image may be any format supported by SDL_image, except TGA.
215If you want to load a TGA image from an sdl2:rwops, you should use {{load-typed-rw}} instead.
216
217If {{close?}} is #t, the sdl2:rwops will be automatically closed after the image is loaded.
218See {{rw-close!}} in the sdl2 egg.
219If {{close?}} is #f (the default), the sdl2:rwops will not be closed.
220
221Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] with the image contents.
222Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
223
224* {{load-rw}} returns a managed sdl2:surface.
225* {{load-rw*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} (from the sdl2 egg) when you are done with it.
226
227
228<procedure>(load-typed-rw  rwops close? type-hint) → sdl2:surface</procedure>
229<procedure>(load-typed-rw* rwops close? type-hint) → sdl2:surface</procedure>
230
231See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC13|IMG_LoadTyped_RW]].
232
233Similar to {{load-rw}}, except you also give a hint to help SDL_image figure out what the image format is.
234In practice, this is only necessary when loading a TGA image from an sdl2:rwops.
235For other image formats you can just use {{load-rw}} instead.
236
237{{type-hint}} must be one of the following strings (case is not important):
238
239* {{"BMP"}}
240* {{"CUR"}}
241* {{"GIF"}}
242* {{"ICO"}}
243* {{"JPG"}}
244* {{"LBM"}}
245* {{"PCX"}}
246* {{"PNG"}}
247* {{"PNM"}}
248* {{"TGA"}}
249* {{"TIF"}}
250* {{"XCF"}}
251* {{"XPM"}}
252* {{"XV"}}
253
254Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the image.
255Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
256
257* {{load-rw-typed}} returns a managed sdl2:surface.
258* {{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.
Note: See TracBrowser for help on using the repository browser.