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

Last change on this file since 37236 was 37236, checked in by John Croisant, 6 months ago

Update sdl2-image wiki for version 0.2.0.

File size: 11.1 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]] 2.0.0 or higher,
27and [[http://www.libsdl.org/projects/SDL_image/|SDL_image]]  2.0 or higher.
28It will not work with older versions of SDL or SDL_image.
29
30This egg requires CHICKEN Scheme 4.8 or higher.
31As of version 0.2.0, this egg is compatible with both CHICKEN 4 and CHICKEN 5.
32
33
34== Installation
35
36In most cases, you can install the sdl2-image egg in the usual way:
37
38 chicken-install sdl2-image
39
40The installer will try to automatically determine the SDL2 compiler and linker flags
41using the {{sdl2-config}} command.
42
43In special cases, you may need to set the
44{{SDL2_CFLAGS}}, {{SDL2_LDFLAGS}}, {{SDL2_IMAGE_CFLAGS}}, and/or {{SDL2_IMAGE_LDFLAGS}}
45environment variables to provide the compiler and linker flags, then try again.
46(The {{SDL2_IMAGE_*}} flags are used in addition to the {{SDL2_*}} flags.)
47
48For example:
49
50 export SDL2_CFLAGS="-I/usr/local/include/SDL2"
51 export SDL2_LDFLAGS="-L/usr/local/lib -lSDL2"
52 export SDL2_IMAGE_LDFLAGS="-lSDL2_image"
53 chicken-install sdl2-image
54
55These environment variables are needed only when installing the egg itself.
56They are not needed when compiling or running programs that use the egg.
57
58=== Installing on macOS
59
60On macOS, the sdl2-image egg can be compiled using either
61UNIX-style libraries (e.g. compiled from source or installed via Homebrew)
62or Mac-style frameworks (e.g. downloaded from the SDL website).
63
64When automatically determining compiler and linker flags on macOS,
65the installer will first check to see if {{sdl2-config}} is available.
66If it is available, the installer will use it to determine the flags.
67
68If {{sdl2-config}} is not available, the installer will check to see if
69{{SDL2.framework}} and {{SDL2_image.framework}} are available
70in either the {{/Library/Frameworks}} or {{/System/Library/Frameworks}} directories.
71If so, the installer will use the frameworks.
72
73If the frameworks are installed in some other directory,
74or if you want to force using the framework even when {{sdl2-config}} is available,
75set the {{SDL2_CFLAGS}}, {{SDL2_LDFLAGS}}, {{SDL2_IMAGE_CFLAGS}}, and/or {{SDL2_IMAGE_LDFLAGS}}
76enviroment variables to tell the compiler where to find the frameworks:
77
78 export SDL2_CFLAGS="-F/path/to/your/frameworks"
79 export SDL2_LDFLAGS="-F/path/to/your/frameworks -framework SDL2"
80 export SDL2_IMAGE_LDFLAGS="-framework SDL2_image"
81 chicken-install sdl2
82
83== Usage and Examples
84
85To avoid procedure name collisions, it is recommended that you import
86the sdl2-image module using a prefix such as "img:", like so:
87
88<enscript highlight="scheme">
89(cond-expand
90  (chicken-4 (use (prefix sdl2 "sdl2:")
91                  (prefix sdl2-image "img:")))
92  (chicken-5 (import (prefix sdl2 "sdl2:")
93                     (prefix sdl2-image "img:"))))
94
95(img:load "image.jpg")
96</enscript>
97
98The [[https://gitlab.com/chicken-sdl2/chicken-sdl2-examples|chicken-sdl2-examples repository]]
99contains complete example games and programs, some of which use the sdl2-image egg.
100
101
102== Version History
103
104; 0.2.0 (2019-02-13) : Ported to be compatible with both CHICKEN 4 and CHICKEN 5. More user-friendly installation process.
105; 0.1.0 (2015-12-19) : Initial release.
106
107For more information about what changed in each version,
108see the [[https://gitlab.com/chicken-sdl2/chicken-sdl2-image/blob/master/CHANGELOG.md|CHANGELOG]].
109
110
111== API
112
113=== Quick Start
114
115<enscript highlight="scheme">
116(cond-expand
117  (chicken-4 (use (prefix sdl2 "sdl2:")
118                  (prefix sdl2-image "img:")
119                  (only lolevel object-evict object-release)))
120  (chicken-5 (import (prefix sdl2 "sdl2:")
121                     (prefix sdl2-image "img:")
122                     object-evict)))
123
124;; Load an image from a file.
125(img:load "path/to/my-image.jpg") ;; or png, gif, etc.
126
127;; Load an image from a blob containing image data.
128;; The blob is evicted to static memory so that it will
129;; not be moved in memory by the garbage collector.
130(let* ((source (object-evict '#${...}))
131       (rwops (sdl2:rw-from-blob source))
132       (surf (img:load-rw rwops #t)))
133  (object-release source)
134  surf)
135
136;; Load an image from a string containing image data.
137;; Like above, the string is evicted.
138(let* ((source (object-evict "..."))
139       (rwops (sdl2:rw-from-string source))
140       (surf (img:load-rw rwops #t)))
141  (object-release source)
142  surf)
143</enscript>
144
145
146=== About the API
147
148==== API Stability
149
150The sdl2-image egg follows "[[http://semver.org/|semantic versioning]]".
151Until version 1.0.0 is released, the API is not guaranteed to be "stable".
152That means the maintainer reserves the right to change the API if needed,
153possibly in ways that break backward compatibility with previous versions.
154'''Large backward-incompatible changes are unlikely''',
155but there may be small tweaks and fixes to the API if problems are discovered.
156
157After version 1.0.0 is released, the API is guaranteed to remain stable (no backward-incompatible changes)
158until the next new major version (e.g. going from version 1.x to 2.0.0, or 2.x to 3.0.0).
159
160==== Conventions
161
162* Procedure names are lower case and hyphenated, with no "IMG_" prefix.
163
164* Procedures that cause a side effect are suffixed with "!".
165
166* Some procedures have two versions: one that returns a managed sdl2:surface, and one that returns an unmanaged sdl2:surface.
167  See [[/egg/sdl2#struct-memory-management|Struct Memory Management]] in the sdl2 egg docs.
168
169* Procedures signal an exception of kind {{(exn sdl2)}} if they fail.
170
171
172=== General
173
174<procedure>(init! #!optional loaders) → list of symbols</procedure>
175
176See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC8|IMG_Init]].
177
178{{loaders}} defaults to {{'(jpg png tif)}}. It must be a list of zero
179or more of those symbols, indicating which image loaders to
180initialize. (Other image formats are built into SDL_image and do not
181need to be initialized.)
182
183Returns a list of symbols indicating all the image loaders that are now initialized.
184You should check the return value to see whether all the image loaders you
185requested were actually initialized. If not, {{get-error}} from the
186sdl2 egg ''might'' return an error message explaining why the image
187loader could not be initialized. (This is a limitation of SDL_image.)
188
189It is not usually necessary to call this procedure. Image loaders will
190automatically be initialized when needed. But, you may wish to call
191this procedure to check whether a loader is available, or to
192initialize the loaders ahead of time to avoid a small delay later.
193
194
195<procedure>(quit!)</procedure>
196
197See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC9|IMG_Quit]].
198
199
200<procedure>(compiled-version) → list of fixnums</procedure>
201<procedure>(current-version)  → list of fixnums</procedure>
202
203Returns a list of three nonnegative integers, indicating a version number of SDL_image.
204For example, the list {{(2 0 0)}} indicates SDL_image 2.0.0.
205
206* {{compiled-version}} returns the version of SDL_image that the sdl2-image egg was compiled with.
207* {{current-version}} returns the version of SDL_image that the sdl2-image egg is currently using.
208
209For 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.
210In such a case, {{compiled-version}} would return {{(2 0 1)}}, and {{current-version}} would return {{(2 0 2)}}.
211But, features from the new version would not be available until the user recompiles the sdl2-image egg.
212
213See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC7|SDL_IMAGE_VERSION and IMG_LinkedVersion]].
214
215
216
217=== Loading
218
219<procedure>(load  filepath) → sdl2:surface</procedure>
220<procedure>(load* filepath) → sdl2:surface</procedure>
221
222Attempts to load the image file at the given filepath (a string).
223The image may be any format supported by SDL_image.
224See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC11|IMG_Load]].
225
226Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] with the image contents.
227Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
228
229* {{load}} returns a managed sdl2:surface.
230* {{load*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} (from the sdl2 egg) when you are done with it.
231
232
233<procedure>(load-rw  rwops #!optional close?) → sdl2:surface</procedure>
234<procedure>(load-rw* rwops #!optional close?) → sdl2:surface</procedure>
235
236Attempts to load an image from an [[/egg/sdl2#rwops|sdl2:rwops]].
237This 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.
238See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC12|IMG_Load_RW]].
239
240The image may be any format supported by SDL_image, except TGA.
241If you want to load a TGA image from an sdl2:rwops, you should use {{load-typed-rw}} instead.
242
243If {{close?}} is #t, the sdl2:rwops will be automatically closed after the image is loaded.
244See {{rw-close!}} in the sdl2 egg.
245If {{close?}} is #f (the default), the sdl2:rwops will not be closed.
246
247Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] with the image contents.
248Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
249
250* {{load-rw}} returns a managed sdl2:surface.
251* {{load-rw*}} returns an unmanaged sdl2:surface, which must be freed with {{free-surface!}} (from the sdl2 egg) when you are done with it.
252
253
254<procedure>(load-typed-rw  rwops close? type-hint) → sdl2:surface</procedure>
255<procedure>(load-typed-rw* rwops close? type-hint) → sdl2:surface</procedure>
256
257See [[http://www.libsdl.org/projects/SDL_image/docs/SDL_image.html#SEC13|IMG_LoadTyped_RW]].
258
259Similar to {{load-rw}}, except you also give a hint to help SDL_image figure out what the image format is.
260In practice, this is only necessary when loading a TGA image from an sdl2:rwops.
261For other image formats you can just use {{load-rw}} instead.
262
263{{type-hint}} must be one of the following strings (case is not important):
264
265* {{"BMP"}}
266* {{"CUR"}}
267* {{"GIF"}}
268* {{"ICO"}}
269* {{"JPG"}}
270* {{"LBM"}}
271* {{"PCX"}}
272* {{"PNG"}}
273* {{"PNM"}}
274* {{"TGA"}}
275* {{"TIF"}}
276* {{"XCF"}}
277* {{"XPM"}}
278* {{"XV"}}
279
280Returns a [[/egg/sdl2#sdl2surface|sdl2:surface]] containing the image.
281Signals an exception of kind {{(exn sdl2)}} if the image could not be loaded.
282
283* {{load-rw-typed}} returns a managed sdl2:surface.
284* {{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.