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 HEADER_SIMPLE_OPENGL_IMAGE_LIBRARY
42
43#ifdef __cplusplus
44extern "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**/
55enum
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**/
71enum
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**/
95enum
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**/
115enum
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**/
137enum
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**/
152unsigned 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**/
174unsigned 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**/
197unsigned 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**/
215unsigned 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**/
234unsigned 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**/
263unsigned 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**/
293unsigned 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**/
315unsigned 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**/
335unsigned 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**/
349int
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**/
367unsigned 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**/
384unsigned 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**/
397int
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**/
411void
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**/
422const 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