1 | /** |
2 | @mainpage SOIL |
3 | |
4 | Jonathan Dummer |
5 | 2007-07-26-10.36 |
6 | |
7 | Simple OpenGL Image Library |
8 | |
9 | A tiny c library for uploading images as |
10 | textures into OpenGL. Also saving and |
11 | loading of images is supported. |
12 | |
13 | I'm using Sean's Tool Box image loader as a base: |
14 | http://www.nothings.org/ |
15 | |
16 | I'm upgrading it to load TGA and DDS files, and a direct |
17 | path for loading DDS files straight into OpenGL textures, |
18 | when applicable. |
19 | |
20 | Image Formats: |
21 | - BMP load & save |
22 | - TGA load & save |
23 | - DDS load & save |
24 | - PNG load |
25 | - JPG load |
26 | |
27 | OpenGL Texture Features: |
28 | - resample to power-of-two sizes |
29 | - MIPmap generation |
30 | - compressed texture S3TC formats (if supported) |
31 | - can pre-multiply alpha for you, for better compositing |
32 | - can flip image about the y-axis (except pre-compressed DDS files) |
33 | |
34 | Thanks to: |
35 | * Sean Barret - for the awesome stb_image |
36 | * Dan Venkitachalam - for finding some non-compliant DDS files, and patching some explicit casts |
37 | * everybody at gamedev.net |
38 | **/ |
39 | |
40 | #ifndef HEADER_SIMPLE_OPENGL_IMAGE_LIBRARY |
41 | #define |
42 | |
43 | #ifdef __cplusplus |
44 | extern "C" { |
45 | #endif |
46 | |
47 | /** |
48 | The format of images that may be loaded (force_channels). |
49 | SOIL_LOAD_AUTO leaves the image in whatever format it was found. |
50 | SOIL_LOAD_L forces the image to load as Luminous (greyscale) |
51 | SOIL_LOAD_LA forces the image to load as Luminous with Alpha |
52 | SOIL_LOAD_RGB forces the image to load as Red Green Blue |
53 | SOIL_LOAD_RGBA forces the image to load as Red Green Blue Alpha |
54 | **/ |
55 | enum |
56 | { |
57 | SOIL_LOAD_AUTO = 0, |
58 | SOIL_LOAD_L = 1, |
59 | SOIL_LOAD_LA = 2, |
60 | SOIL_LOAD_RGB = 3, |
61 | SOIL_LOAD_RGBA = 4 |
62 | }; |
63 | |
64 | /** |
65 | Passed in as reuse_texture_ID, will cause SOIL to |
66 | register a new texture ID using glGenTextures(). |
67 | If the value passed into reuse_texture_ID > 0 then |
68 | SOIL will just re-use that texture ID (great for |
69 | reloading image assets in-game!) |
70 | **/ |
71 | enum |
72 | { |
73 | SOIL_CREATE_NEW_ID = 0 |
74 | }; |
75 | |
76 | /** |
77 | flags you can pass into SOIL_load_OGL_texture() |
78 | and SOIL_create_OGL_texture(). |
79 | (note that if SOIL_FLAG_DDS_LOAD_DIRECT is used |
80 | the rest of the flags with the exception of |
81 | SOIL_FLAG_TEXTURE_REPEATS will be ignored while |
82 | loading already-compressed DDS files.) |
83 | |
84 | SOIL_FLAG_POWER_OF_TWO: force the image to be POT |
85 | SOIL_FLAG_MIPMAPS: generate mipmaps for the texture |
86 | SOIL_FLAG_TEXTURE_REPEATS: otherwise will clamp |
87 | SOIL_FLAG_MULTIPLY_ALPHA: for using (GL_ONE,GL_ONE_MINUS_SRC_ALPHA) blending |
88 | SOIL_FLAG_INVERT_Y: flip the image vertically |
89 | SOIL_FLAG_COMPRESS_TO_DXT: if the card can display them, will convert RGB to DXT1, RGBA to DXT5 |
90 | SOIL_FLAG_DDS_LOAD_DIRECT: will load DDS files directly without _ANY_ additional processing |
91 | SOIL_FLAG_NTSC_SAFE_RGB: clamps RGB components to the range [16,235] |
92 | SOIL_FLAG_CoCg_Y: Google YCoCg; RGB=>CoYCg, RGBA=>CoCgAY |
93 | SOIL_FLAG_TEXTURE_RECTANGE: uses ARB_texture_rectangle ; pixel indexed & no repeat or MIPmaps or cubemaps |
94 | **/ |
95 | enum |
96 | { |
97 | SOIL_FLAG_POWER_OF_TWO = 1, |
98 | SOIL_FLAG_MIPMAPS = 2, |
99 | SOIL_FLAG_TEXTURE_REPEATS = 4, |
100 | SOIL_FLAG_MULTIPLY_ALPHA = 8, |
101 | SOIL_FLAG_INVERT_Y = 16, |
102 | SOIL_FLAG_COMPRESS_TO_DXT = 32, |
103 | SOIL_FLAG_DDS_LOAD_DIRECT = 64, |
104 | SOIL_FLAG_NTSC_SAFE_RGB = 128, |
105 | SOIL_FLAG_CoCg_Y = 256, |
106 | SOIL_FLAG_TEXTURE_RECTANGLE = 512 |
107 | }; |
108 | |
109 | /** |
110 | The types of images that may be saved. |
111 | (TGA supports uncompressed RGB / RGBA) |
112 | (BMP supports uncompressed RGB) |
113 | (DDS supports DXT1 and DXT5) |
114 | **/ |
115 | enum |
116 | { |
117 | SOIL_SAVE_TYPE_TGA = 0, |
118 | SOIL_SAVE_TYPE_BMP = 1, |
119 | SOIL_SAVE_TYPE_DDS = 2 |
120 | }; |
121 | |
122 | /** |
123 | Defines the order of faces in a DDS cubemap. |
124 | I recommend that you use the same order in single |
125 | image cubemap files, so they will be interchangeable |
126 | with DDS cubemaps when using SOIL. |
127 | **/ |
128 | #define SOIL_DDS_CUBEMAP_FACE_ORDER "EWUDNS" |
129 | |
130 | /** |
131 | The types of internal fake HDR representations |
132 | |
133 | SOIL_HDR_RGBE: RGB * pow( 2.0, A - 128.0 ) |
134 | SOIL_HDR_RGBdivA: RGB / A |
135 | SOIL_HDR_RGBdivA2: RGB / (A*A) |
136 | **/ |
137 | enum |
138 | { |
139 | SOIL_HDR_RGBE = 0, |
140 | SOIL_HDR_RGBdivA = 1, |
141 | SOIL_HDR_RGBdivA2 = 2 |
142 | }; |
143 | |
144 | /** |
145 | Loads an image from disk into an OpenGL texture. |
146 | \param filename the name of the file to upload as a texture |
147 | \param force_channels 0-image format, 1-luminous, 2-luminous/alpha, 3-RGB, 4-RGBA |
148 | \param reuse_texture_ID 0-generate a new texture ID, otherwise reuse the texture ID (overwriting the old texture) |
149 | \param flags can be any of SOIL_FLAG_POWER_OF_TWO | SOIL_FLAG_MIPMAPS | SOIL_FLAG_TEXTURE_REPEATS | SOIL_FLAG_MULTIPLY_ALPHA | SOIL_FLAG_INVERT_Y | SOIL_FLAG_COMPRESS_TO_DXT | SOIL_FLAG_DDS_LOAD_DIRECT |
150 | \return 0-failed, otherwise returns the OpenGL texture handle |
151 | **/ |
152 | unsigned int |
153 | SOIL_load_OGL_texture |
154 | ( |
155 | const char *filename, |
156 | int force_channels, |
157 | unsigned int reuse_texture_ID, |
158 | unsigned int flags |
159 | ); |
160 | |
161 | /** |
162 | Loads 6 images from disk into an OpenGL cubemap texture. |
163 | \param x_pos_file the name of the file to upload as the +x cube face |
164 | \param x_neg_file the name of the file to upload as the -x cube face |
165 | \param y_pos_file the name of the file to upload as the +y cube face |
166 | \param y_neg_file the name of the file to upload as the -y cube face |
167 | \param z_pos_file the name of the file to upload as the +z cube face |
168 | \param z_neg_file the name of the file to upload as the -z cube face |
169 | \param force_channels 0-image format, 1-luminous, 2-luminous/alpha, 3-RGB, 4-RGBA |
170 | \param reuse_texture_ID 0-generate a new texture ID, otherwise reuse the texture ID (overwriting the old texture) |
171 | \param flags can be any of SOIL_FLAG_POWER_OF_TWO | SOIL_FLAG_MIPMAPS | SOIL_FLAG_TEXTURE_REPEATS | SOIL_FLAG_MULTIPLY_ALPHA | SOIL_FLAG_INVERT_Y | SOIL_FLAG_COMPRESS_TO_DXT | SOIL_FLAG_DDS_LOAD_DIRECT |
172 | \return 0-failed, otherwise returns the OpenGL texture handle |
173 | **/ |
174 | unsigned int |
175 | SOIL_load_OGL_cubemap |
176 | ( |
177 | const char *x_pos_file, |
178 | const char *x_neg_file, |
179 | const char *y_pos_file, |
180 | const char *y_neg_file, |
181 | const char *z_pos_file, |
182 | const char *z_neg_file, |
183 | int force_channels, |
184 | unsigned int reuse_texture_ID, |
185 | unsigned int flags |
186 | ); |
187 | |
188 | /** |
189 | Loads 1 image from disk and splits it into an OpenGL cubemap texture. |
190 | \param filename the name of the file to upload as a texture |
191 | \param face_order the order of the faces in the file, any combination of NSWEUD, for North, South, Up, etc. |
192 | \param force_channels 0-image format, 1-luminous, 2-luminous/alpha, 3-RGB, 4-RGBA |
193 | \param reuse_texture_ID 0-generate a new texture ID, otherwise reuse the texture ID (overwriting the old texture) |
194 | \param flags can be any of SOIL_FLAG_POWER_OF_TWO | SOIL_FLAG_MIPMAPS | SOIL_FLAG_TEXTURE_REPEATS | SOIL_FLAG_MULTIPLY_ALPHA | SOIL_FLAG_INVERT_Y | SOIL_FLAG_COMPRESS_TO_DXT | SOIL_FLAG_DDS_LOAD_DIRECT |
195 | \return 0-failed, otherwise returns the OpenGL texture handle |
196 | **/ |
197 | unsigned int |
198 | SOIL_load_OGL_single_cubemap |
199 | ( |
200 | const char *filename, |
201 | const char face_order[6], |
202 | int force_channels, |
203 | unsigned int reuse_texture_ID, |
204 | unsigned int flags |
205 | ); |
206 | |
207 | /** |
208 | Loads an HDR image from disk into an OpenGL texture. |
209 | \param filename the name of the file to upload as a texture |
210 | \param fake_HDR_format SOIL_HDR_RGBE, SOIL_HDR_RGBdivA, SOIL_HDR_RGBdivA2 |
211 | \param reuse_texture_ID 0-generate a new texture ID, otherwise reuse the texture ID (overwriting the old texture) |
212 | \param flags can be any of SOIL_FLAG_POWER_OF_TWO | SOIL_FLAG_MIPMAPS | SOIL_FLAG_TEXTURE_REPEATS | SOIL_FLAG_MULTIPLY_ALPHA | SOIL_FLAG_INVERT_Y | SOIL_FLAG_COMPRESS_TO_DXT |
213 | \return 0-failed, otherwise returns the OpenGL texture handle |
214 | **/ |
215 | unsigned int |
216 | SOIL_load_OGL_HDR_texture |
217 | ( |
218 | const char *filename, |
219 | int fake_HDR_format, |
220 | int rescale_to_max, |
221 | unsigned int reuse_texture_ID, |
222 | unsigned int flags |
223 | ); |
224 | |
225 | /** |
226 | Loads an image from RAM into an OpenGL texture. |
227 | \param buffer the image data in RAM just as if it were still in a file |
228 | \param buffer_length the size of the buffer in bytes |
229 | \param force_channels 0-image format, 1-luminous, 2-luminous/alpha, 3-RGB, 4-RGBA |
230 | \param reuse_texture_ID 0-generate a new texture ID, otherwise reuse the texture ID (overwriting the old texture) |
231 | \param flags can be any of SOIL_FLAG_POWER_OF_TWO | SOIL_FLAG_MIPMAPS | SOIL_FLAG_TEXTURE_REPEATS | SOIL_FLAG_MULTIPLY_ALPHA | SOIL_FLAG_INVERT_Y | SOIL_FLAG_COMPRESS_TO_DXT | SOIL_FLAG_DDS_LOAD_DIRECT |
232 | \return 0-failed, otherwise returns the OpenGL texture handle |
233 | **/ |
234 | unsigned int |
235 | SOIL_load_OGL_texture_from_memory |
236 | ( |
237 | const unsigned char *const buffer, |
238 | int buffer_length, |
239 | int force_channels, |
240 | unsigned int reuse_texture_ID, |
241 | unsigned int flags |
242 | ); |
243 | |
244 | /** |
245 | Loads 6 images from memory into an OpenGL cubemap texture. |
246 | \param x_pos_buffer the image data in RAM to upload as the +x cube face |
247 | \param x_pos_buffer_length the size of the above buffer |
248 | \param x_neg_buffer the image data in RAM to upload as the +x cube face |
249 | \param x_neg_buffer_length the size of the above buffer |
250 | \param y_pos_buffer the image data in RAM to upload as the +x cube face |
251 | \param y_pos_buffer_length the size of the above buffer |
252 | \param y_neg_buffer the image data in RAM to upload as the +x cube face |
253 | \param y_neg_buffer_length the size of the above buffer |
254 | \param z_pos_buffer the image data in RAM to upload as the +x cube face |
255 | \param z_pos_buffer_length the size of the above buffer |
256 | \param z_neg_buffer the image data in RAM to upload as the +x cube face |
257 | \param z_neg_buffer_length the size of the above buffer |
258 | \param force_channels 0-image format, 1-luminous, 2-luminous/alpha, 3-RGB, 4-RGBA |
259 | \param reuse_texture_ID 0-generate a new texture ID, otherwise reuse the texture ID (overwriting the old texture) |
260 | \param flags can be any of SOIL_FLAG_POWER_OF_TWO | SOIL_FLAG_MIPMAPS | SOIL_FLAG_TEXTURE_REPEATS | SOIL_FLAG_MULTIPLY_ALPHA | SOIL_FLAG_INVERT_Y | SOIL_FLAG_COMPRESS_TO_DXT | SOIL_FLAG_DDS_LOAD_DIRECT |
261 | \return 0-failed, otherwise returns the OpenGL texture handle |
262 | **/ |
263 | unsigned int |
264 | SOIL_load_OGL_cubemap_from_memory |
265 | ( |
266 | const unsigned char *const x_pos_buffer, |
267 | int x_pos_buffer_length, |
268 | const unsigned char *const x_neg_buffer, |
269 | int x_neg_buffer_length, |
270 | const unsigned char *const y_pos_buffer, |
271 | int y_pos_buffer_length, |
272 | const unsigned char *const y_neg_buffer, |
273 | int y_neg_buffer_length, |
274 | const unsigned char *const z_pos_buffer, |
275 | int z_pos_buffer_length, |
276 | const unsigned char *const z_neg_buffer, |
277 | int z_neg_buffer_length, |
278 | int force_channels, |
279 | unsigned int reuse_texture_ID, |
280 | unsigned int flags |
281 | ); |
282 | |
283 | /** |
284 | Loads 1 image from RAM and splits it into an OpenGL cubemap texture. |
285 | \param buffer the image data in RAM just as if it were still in a file |
286 | \param buffer_length the size of the buffer in bytes |
287 | \param face_order the order of the faces in the file, any combination of NSWEUD, for North, South, Up, etc. |
288 | \param force_channels 0-image format, 1-luminous, 2-luminous/alpha, 3-RGB, 4-RGBA |
289 | \param reuse_texture_ID 0-generate a new texture ID, otherwise reuse the texture ID (overwriting the old texture) |
290 | \param flags can be any of SOIL_FLAG_POWER_OF_TWO | SOIL_FLAG_MIPMAPS | SOIL_FLAG_TEXTURE_REPEATS | SOIL_FLAG_MULTIPLY_ALPHA | SOIL_FLAG_INVERT_Y | SOIL_FLAG_COMPRESS_TO_DXT | SOIL_FLAG_DDS_LOAD_DIRECT |
291 | \return 0-failed, otherwise returns the OpenGL texture handle |
292 | **/ |
293 | unsigned int |
294 | SOIL_load_OGL_single_cubemap_from_memory |
295 | ( |
296 | const unsigned char *const buffer, |
297 | int buffer_length, |
298 | const char face_order[6], |
299 | int force_channels, |
300 | unsigned int reuse_texture_ID, |
301 | unsigned int flags |
302 | ); |
303 | |
304 | /** |
305 | Creates a 2D OpenGL texture from raw image data. Note that the raw data is |
306 | _NOT_ freed after the upload (so the user can load various versions). |
307 | \param data the raw data to be uploaded as an OpenGL texture |
308 | \param width the width of the image in pixels |
309 | \param height the height of the image in pixels |
310 | \param channels the number of channels: 1-luminous, 2-luminous/alpha, 3-RGB, 4-RGBA |
311 | \param reuse_texture_ID 0-generate a new texture ID, otherwise reuse the texture ID (overwriting the old texture) |
312 | \param flags can be any of SOIL_FLAG_POWER_OF_TWO | SOIL_FLAG_MIPMAPS | SOIL_FLAG_TEXTURE_REPEATS | SOIL_FLAG_MULTIPLY_ALPHA | SOIL_FLAG_INVERT_Y | SOIL_FLAG_COMPRESS_TO_DXT |
313 | \return 0-failed, otherwise returns the OpenGL texture handle |
314 | **/ |
315 | unsigned int |
316 | SOIL_create_OGL_texture |
317 | ( |
318 | const unsigned char *const data, |
319 | int width, int height, int channels, |
320 | unsigned int reuse_texture_ID, |
321 | unsigned int flags |
322 | ); |
323 | |
324 | /** |
325 | Creates an OpenGL cubemap texture by splitting up 1 image into 6 parts. |
326 | \param data the raw data to be uploaded as an OpenGL texture |
327 | \param width the width of the image in pixels |
328 | \param height the height of the image in pixels |
329 | \param channels the number of channels: 1-luminous, 2-luminous/alpha, 3-RGB, 4-RGBA |
330 | \param face_order the order of the faces in the file, and combination of NSWEUD, for North, South, Up, etc. |
331 | \param reuse_texture_ID 0-generate a new texture ID, otherwise reuse the texture ID (overwriting the old texture) |
332 | \param flags can be any of SOIL_FLAG_POWER_OF_TWO | SOIL_FLAG_MIPMAPS | SOIL_FLAG_TEXTURE_REPEATS | SOIL_FLAG_MULTIPLY_ALPHA | SOIL_FLAG_INVERT_Y | SOIL_FLAG_COMPRESS_TO_DXT | SOIL_FLAG_DDS_LOAD_DIRECT |
333 | \return 0-failed, otherwise returns the OpenGL texture handle |
334 | **/ |
335 | unsigned int |
336 | SOIL_create_OGL_single_cubemap |
337 | ( |
338 | const unsigned char *const data, |
339 | int width, int height, int channels, |
340 | const char face_order[6], |
341 | unsigned int reuse_texture_ID, |
342 | unsigned int flags |
343 | ); |
344 | |
345 | /** |
346 | Captures the OpenGL window (RGB) and saves it to disk |
347 | \return 0 if it failed, otherwise returns 1 |
348 | **/ |
349 | int |
350 | SOIL_save_screenshot |
351 | ( |
352 | const char *filename, |
353 | int image_type, |
354 | int x, int y, |
355 | int width, int height |
356 | ); |
357 | |
358 | /** |
359 | Loads an image from disk into an array of unsigned chars. |
360 | Note that *channels return the original channel count of the |
361 | image. If force_channels was other than SOIL_LOAD_AUTO, |
362 | the resulting image has force_channels, but *channels may be |
363 | different (if the original image had a different channel |
364 | count). |
365 | \return 0 if failed, otherwise returns 1 |
366 | **/ |
367 | unsigned char* |
368 | SOIL_load_image |
369 | ( |
370 | const char *filename, |
371 | int *width, int *height, int *channels, |
372 | int force_channels |
373 | ); |
374 | |
375 | /** |
376 | Loads an image from memory into an array of unsigned chars. |
377 | Note that *channels return the original channel count of the |
378 | image. If force_channels was other than SOIL_LOAD_AUTO, |
379 | the resulting image has force_channels, but *channels may be |
380 | different (if the original image had a different channel |
381 | count). |
382 | \return 0 if failed, otherwise returns 1 |
383 | **/ |
384 | unsigned char* |
385 | SOIL_load_image_from_memory |
386 | ( |
387 | const unsigned char *const buffer, |
388 | int buffer_length, |
389 | int *width, int *height, int *channels, |
390 | int force_channels |
391 | ); |
392 | |
393 | /** |
394 | Saves an image from an array of unsigned chars (RGBA) to disk |
395 | \return 0 if failed, otherwise returns 1 |
396 | **/ |
397 | int |
398 | SOIL_save_image |
399 | ( |
400 | const char *filename, |
401 | int image_type, |
402 | int width, int height, int channels, |
403 | const unsigned char *const data |
404 | ); |
405 | |
406 | /** |
407 | Frees the image data (note, this is just C's "free()"...this function is |
408 | present mostly so C++ programmers don't forget to use "free()" and call |
409 | "delete []" instead [8^) |
410 | **/ |
411 | void |
412 | SOIL_free_image_data |
413 | ( |
414 | unsigned char *img_data |
415 | ); |
416 | |
417 | /** |
418 | This function resturn a pointer to a string describing the last thing |
419 | that happened inside SOIL. It can be used to determine why an image |
420 | failed to load. |
421 | **/ |
422 | const char* |
423 | SOIL_last_result |
424 | ( |
425 | void |
426 | ); |
427 | |
428 | |
429 | #ifdef __cplusplus |
430 | } |
431 | #endif |
432 | |
433 | #endif /* HEADER_SIMPLE_OPENGL_IMAGE_LIBRARY */ |
434 | |