forked from kbranigan/Simple-OpenGL-Image-Library
-
Notifications
You must be signed in to change notification settings - Fork 2
/
soil.html
320 lines (309 loc) · 17.9 KB
/
soil.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
<TITLE>lonesock.net: SOIL</TITLE>
<style type="text/css">
<!--
body { color: #000000; background-color: #FFFFFF; }
.style1 { color: #505050; }
.style2 { color: #A0A0A0; }
.style3 { color: #8080FF; font-weight: bold; }
.style15 { color: #8080FF; font-weight: bold; }
.style17 { color: #008080; }
.style18 { color: #800000; }
.style4 { color: #F000F0; }
.style5 { color: #0000A0; font-weight: bold; }
.style16 { color: #00A000; font-weight: bold; }
.style6 { color: #0000FF; }
.style12 { color: #0000FF; }
.style7 { color: #E0A000; }
.style8 { color: #000000; }
.style9 { color: #00A000; }
.style10 { color: #FF0000; }
.style34 { color: #000000; background-color: #80FFFF; font-weight: bold; }
.style35 { color: #FFFFFF; background-color: #FF0000; font-weight: bold; }
--></style>
</HEAD>
<BODY LANG="en-US" DIR="LTR">
<PRE STYLE="margin-bottom: 0.2in; text-align: center">
<FONT SIZE=4 STYLE="font-size: 16pt"><B>Simple OpenGL Image Library</B></FONT>
</PRE>
<P>
<B>Introduction:</B><BR><BR>SOIL is a tiny C library used primarily
for uploading textures into OpenGL. It is based on stb_image version
1.16, the public domain code from Sean Barrett (found <A HREF="http://www.nothings.org/stb_image.c">here</A>).
I have extended it to load TGA and DDS files, and to perform common
functions needed in loading OpenGL textures. SOIL can also be used
to save and load images in a variety of formats (useful for loading
height maps, non-OpenGL applications, etc.)<BR>
<BR>
<B>Download:</B>
<BR>
<BR>
You can grab the latest version of SOIL <A HREF="http://www.lonesock.net/files/soil.zip">here</A>.
(July 7, 2008: see the change log at the bottom of this page.)<BR>
You can also checkout the latest code from the new SVN repository, login as guest/guest:<BR>
<A HREF="svn://www.twisted-works.com/jdummer/public/SOIL">svn://www.twisted-works.com/jdummer/public/SOIL</A><BR>
(thanks for the SVN hosting, Sherief!)
<BR>
<BR>
<B>License:</B>
<BR>
<BR>
Public Domain
<BR>
<BR>
<B>Features:</B>
</P>
<UL>
<LI>Readable Image Formats:
<UL>
<LI>BMP - non-1bpp, non-RLE (from stb_image documentation)
<LI>PNG - non-interlaced (from stb_image documentation)
<LI>JPG - JPEG baseline (from stb_image documentation)
<LI>TGA - greyscale or RGB or RGBA or indexed, uncompressed or RLE
<LI>DDS - DXT1/2/3/4/5, uncompressed, cubemaps (can't read 3D DDS files yet)
<LI>PSD - (from stb_image documentation)
<LI>HDR - converted to LDR, unless loaded with *HDR* functions (RGBE or RGBdivA or RGBdivA2)
</UL>
<LI>Writeable Image Formats:
<UL>
<LI>TGA - Greyscale or RGB or RGBA, uncompressed
<LI>BMP - RGB, uncompressed
<LI>DDS - RGB as DXT1, or RGBA as DXT5
</UL>
<LI>Can load an image file directly into a 2D OpenGL texture, optionally performing the following functions:
<UL>
<LI>Can generate a new texture handle, or reuse one specified
<LI>Can automatically rescale the image to the next largest power-of-two size
<LI>Can automatically create MIPmaps
<LI>Can scale (not simply clamp) the RGB values into the "safe range" for NTSC displays (16 to 235, as recommended <a href="http://msdn2.microsoft.com/en-us/library/bb174608.aspx#NTSC_Suggestions">here</a>)
<LI>Can multiply alpha on load (for more correct blending / compositing)
<LI>Can flip the image vertically
<LI>Can compress and upload any image as DXT1 or DXT5 (if EXT_texture_compression_s3tc is available), using an internal (very fast!) compressor
<LI>Can convert the RGB to YCoCg color space (useful with DXT5 compression: see <a href="http://developer.nvidia.com/object/real-time-ycocg-dxt-compression.html">this link</a> from NVIDIA)
<LI>Will automatically downsize a texture if it is larger than GL_MAX_TEXTURE_SIZE
<LI>Can directly upload DDS files (DXT1/3/5/uncompressed/cubemap, with or without MIPmaps). Note: directly uploading the compressed DDS image will disable the other options (no flipping, no pre-multiplying alpha, no rescaling, no creation of MIPmaps, no auto-downsizing)
<LI>Can load rectangluar textures for GUI elements or splash screens (requires GL_ARB/EXT/NV_texture_rectangle)
</UL>
<LI>Can decompress images from RAM (e.g. via <a href="http://icculus.org/physfs/">PhysicsFS</a> or similar) into an OpenGL texture (same features as regular 2D textures, above)
<LI>Can load cube maps directly into an OpenGL texture (same features as regular 2D textures, above)
<UL>
<LI>Can take six image files directly into an OpenGL cube map texture
<LI>Can take a single image file where width = 6*height (or vice versa), split it into an OpenGL cube map texture
</UL>
<LI>No external dependencies
<LI>Tiny
<LI>Cross platform (Windows, *nix, Mac OS X)
<LI>Public Domain
</UL>
<PRE STYLE="margin-bottom: 0.2in"><B>ToDo:</B></PRE>
<UL>
<LI>More testing
<LI>add HDR functions to load from memory and load to RGBE unsigned char*
</UL>
<P><BR><B>Usage:</B><BR><BR>SOIL is meant to be used as a static
library (as it's tiny and in the public domain). You can use the static
library file included in the zip (libSOIL.a works for MinGW and Microsoft
compilers...feel free to rename it to SOIL.lib if that makes you happy),
or compile the library yourself. The code is cross-platform and has been
tested on Windows, Linux, and Mac. (The heaviest testing has been on the
Windows platform, so feel free to email me if you find any issues with
other platforms.)
<BR><BR>Simply include SOIL.h in your C or C++ file,
link in the static library, and then use any of SOIL's functions. The
file SOIL.h contains simple doxygen style documentation. (If you use the
static library, no other header files are needed besides SOIL.h) Below
are some simple usage examples:
</P>
<pre>
<code><span style="font: 8pt Courier New;"><span class="style1">/* load an image file directly as a new OpenGL texture */
</span><span class="style11">GLuint tex_2d </span><span class="style10">= </span><span class="style11">SOIL_load_OGL_texture
</span><span class="style10">(
</span><span class="style6">"img.png"</span><span class="style10">,
</span><span class="style11">SOIL_LOAD_AUTO</span><span class="style10">,
</span><span class="style11">SOIL_CREATE_NEW_ID</span><span class="style10">,
</span><span class="style11">SOIL_FLAG_MIPMAPS </span><span class="style10">| </span><span class="style11">SOIL_FLAG_INVERT_Y </span><span class="style10">| </span><span class="style11">SOIL_FLAG_NTSC_SAFE_RGB </span><span class="style10">| </span><span class="style11">SOIL_FLAG_COMPRESS_TO_DXT
</span><span class="style10">);
</span><span class="style1">/* check for an error during the load process */
</span><span class="style5">if</span><span class="style10">( </span><span class="style4">0 </span><span class="style10">== </span><span class="style11">tex_2d </span><span class="style10">)
{
</span><span class="style11">printf</span><span class="style10">( </span><span class="style6">"SOIL loading error: '%s'\n"</span><span class="style10">, </span><span class="style11">SOIL_last_result</span><span class="style10">() );
}
</span><span class="style1">/* load another image, but into the same texture ID, overwriting the last one */
</span><span class="style11">tex_2d </span><span class="style10">= </span><span class="style11">SOIL_load_OGL_texture
</span><span class="style10">(
</span><span class="style6">"some_other_img.dds"</span><span class="style10">,
</span><span class="style11">SOIL_LOAD_AUTO</span><span class="style10">,
</span><span class="style11">tex_2d</span><span class="style10">,
</span><span class="style11">SOIL_FLAG_DDS_LOAD_DIRECT
</span><span class="style10">);
</span><span class="style1">/* load 6 images into a new OpenGL cube map, forcing RGB */
</span><span class="style11">GLuint tex_cube </span><span class="style10">= </span><span class="style11">SOIL_load_OGL_cubemap
</span><span class="style10">(
</span><span class="style6">"xp.jpg"</span><span class="style10">,
</span><span class="style6">"xn.jpg"</span><span class="style10">,
</span><span class="style6">"yp.jpg"</span><span class="style10">,
</span><span class="style6">"yn.jpg"</span><span class="style10">,
</span><span class="style6">"zp.jpg"</span><span class="style10">,
</span><span class="style6">"zn.jpg"</span><span class="style10">,
</span><span class="style11">SOIL_LOAD_RGB</span><span class="style10">,
</span><span class="style11">SOIL_CREATE_NEW_ID</span><span class="style10">,
</span><span class="style11">SOIL_FLAG_MIPMAPS
</span><span class="style10">);
</span><span class="style1">/* load and split a single image into a new OpenGL cube map, default format */
</span><span class="style1">/* face order = East South West North Up Down => "ESWNUD", case sensitive! */
</span><span class="style11">GLuint single_tex_cube </span><span class="style10">= </span><span class="style11">SOIL_load_OGL_single_cubemap
</span><span class="style10">(
</span><span class="style6">"split_cubemap.png"</span><span class="style10">,
</span><span class="style6">"EWUDNS"</span><span class="style10">,
</span><span class="style11">SOIL_LOAD_AUTO</span><span class="style10">,
</span><span class="style11">SOIL_CREATE_NEW_ID</span><span class="style10">,
</span><span class="style11">SOIL_FLAG_MIPMAPS
</span><span class="style10">);
</span><span class="style1">/* actually, load a DDS cubemap over the last OpenGL cube map, default format */
</span><span class="style1">/* try to load it directly, but give the order of the faces in case that fails */
</span><span class="style1">/* the DDS cubemap face order is pre-defined as SOIL_DDS_CUBEMAP_FACE_ORDER */
</span><span class="style11">single_tex_cube </span><span class="style10">= </span><span class="style11">SOIL_load_OGL_single_cubemap
</span><span class="style10">(
</span><span class="style6">"overwrite_cubemap.dds"</span><span class="style10">,
</span><span class="style11">SOIL_DDS_CUBEMAP_FACE_ORDER</span><span class="style10">,
</span><span class="style11">SOIL_LOAD_AUTO</span><span class="style10">,
</span><span class="style11">single_tex_cube</span><span class="style10">,
</span><span class="style11">SOIL_FLAG_MIPMAPS | SOIL_FLAG_DDS_LOAD_DIRECT
</span><span class="style10">);
</span><span class="style1">/* load an image as a heightmap, forcing greyscale (so channels should be 1) */
</span><span class="style5">int </span><span class="style11">width</span><span class="style10">, </span><span class="style11">height</span><span class="style10">, </span><span class="style11">channels</span><span class="style10">;
</span><span class="style5">unsigned char </span><span class="style10">*</span><span class="style11">ht_map </span><span class="style10">= </span><span class="style11">SOIL_load_image
</span><span class="style10">(
</span><span class="style6">"terrain.tga"</span><span class="style10">,
&</span><span class="style11">width</span><span class="style10">, &</span><span class="style11">height</span><span class="style10">, &</span><span class="style11">channels</span><span class="style10">,
</span><span class="style11">SOIL_LOAD_L
</span><span class="style10">);
</span><span class="style1">/* save that image as another type */
</span><span class="style5">int </span><span class="style11">save_result </span><span class="style10">= </span><span class="style11">SOIL_save_image
</span><span class="style10">(
</span><span class="style6">"new_terrain.dds"</span><span class="style10">,
</span><span class="style11">SOIL_SAVE_TYPE_DDS</span><span class="style10">,
</span><span class="style11">width</span><span class="style10">, </span><span class="style11">height</span><span class="style10">, </span><span class="style11">channels</span><span class="style10">,
</span><span class="style11">ht_map
</span><span class="style10">);
</span><span class="style1">/* save a screenshot of your awesome OpenGL game engine, running at 1024x768 */
</span><span class="style11">save_result </span><span class="style10">= </span><span class="style11">SOIL_save_screenshot
</span><span class="style10">(
</span><span class="style6">"awesomenessity.bmp"</span><span class="style10">,
</span><span class="style11">SOIL_SAVE_TYPE_BMP</span><span class="style10">,
</span><span class="style4">0</span><span class="style10">, </span><span class="style4">0</span><span class="style10">, </span><span class="style4">1024</span><span class="style10">, </span><span class="style4">768
</span><span class="style10">);
</span><span class="style1">/* loaded a file via PhysicsFS, need to decompress the image from RAM, */
</span><span class="style1">/* where it's in a buffer: unsigned char *image_in_RAM */
</span><span class="style11">GLuint tex_2d_from_RAM </span><span class="style10">= </span><span class="style11">SOIL_load_OGL_texture_from_memory
</span><span class="style10">(
</span><span class="style11">image_in_RAM</span><span class="style10">,
</span><span class="style11">image_in_RAM_bytes</span><span class="style10">,
</span><span class="style11">SOIL_LOAD_AUTO</span><span class="style10">,
</span><span class="style11">SOIL_CREATE_NEW_ID</span><span class="style10">,
</span><span class="style11">SOIL_FLAG_MIPMAPS </span><span class="style10">| </span><span class="style11">SOIL_FLAG_INVERT_Y </span><span class="style10">| </span><span class="style11">SOIL_FLAG_COMPRESS_TO_DXT
</span><span class="style10">);
</span><span class="style1">/* done with the heightmap, free up the RAM */
</span><span class="style11">SOIL_free_image_data</span><span class="style10">( </span><span class="style11">ht_map </span><span class="style10">);</span></span>
</code></pre>
<BR>
<BR>
<B>Change Log:</B>
<UL>
<LI>July 7, 2008
<UL>
<LI>upgraded to stb_image 1.16 (threadsafe! loads PSD and HDR formats)
<LI>removed <B>inline</B> keyword from native SOIL functions (thanks Sherief, Boder, Amnesiac5!)
<LI>added SOIL_load_OGL_HDR_texture (loads a Radience HDR file into RGBE, RGB/a, RGB/A^2)
<LI>fixed a potential bug loading DDS files with a filename
<LI>added a VC9 project file (thanks Sherief!)
</UL>
<LI>November 10, 2007: added SOIL_FLAG_TEXTURE_RECTANGLE (pixel addressed non POT, useful for GUI, splash screens, etc.). Not useful with cubemaps, and disables repeating and MIPmaps.
<LI>November 8, 2007
<UL>
<LI>upgraded to stb_image 1.07
<LI>fixed some includes and defines for compiling on OS X (thanks Mogui and swiftcoder!)
</UL>
<LI>October 30, 2007
<UL>
<LI>upgraded to stb_image 1.04, some tiny bug fixes
<LI>there is now a makefile (under projects) for ease of building under Linux (thanks D J Peters!)
<LI>Visual Studio 6/2003/2005 projects are working again
<LI>patched SOIL for better pointer handling of the glCompressedTexImage2D extension (thanks Peter Sperl!)
<LI>fixed DDS loading when force_channels=4 but there was no alpha; it was returning 3 channels. (Thanks LaurentGom!)
<LI>fixed a bunch of channel issues in general. (Thanks Sean Barrett!)
</UL>
<LI>October 27, 2007
<UL>
<LI>correctly reports when there is no OpenGL context (thanks Merick Zero!)
<LI>upgraded to stb_image 1.03 with support for loading the HDR image format
<LI>fixed loading JPEG images while forcing the number of channels (e.g. to RGBA)
<LI>changed SOIL_DDS_CUBEMAP_FACE_ORDER to a #define (thanks Dancho!)
<LI>reorganized my additions to stb_image (you can define STBI_NO_DDS to compile SOIL without DDS support)
<LI>added SOIL_FLAG_CoCg_Y, will convert RGB or RGBA to YCoCg color space (<a href="http://developer.nvidia.com/object/real-time-ycocg-dxt-compression.html">link</a>)
</UL>
<LI>October 5, 2007
<UL>
<LI>added SOIL_FLAG_NTSC_SAFE_RGB
<LI>bugfixed & optimized up_scale_image (used with SOIL_FLAG_POWER_OF_TWO and SOIL_FLAG_MIPMAPS)
</UL>
<LI>September 20, 2007
<UL>
<LI>upgraded to stb_image 1.0
<LI>added the DXT source files to the MSVS projects
<LI>removed sqrtf() calls (VS2k3 could not handle them)
<LI>distributing only 1 library file (libSOIL.a, compiled with MinGW 4.2.1 tech preview!) for all windows compilers
<LI>added an example of the *_from_memory() functions to the Usage section
</UL>
<LI>September 6, 2007
<UL>
<LI>added a slew of SOIL_load_*_from_memory() functions for people using PhysicsFS or similar
<LI>more robust loading of non-compliant DDS files (thanks Dan!)
</UL>
<LI>September 1, 2007 - fixed bugs from the last update [8^)
<LI>August 31, 2007
<UL>
<LI>can load uncompressed and cubemap DDS files
<LI>can create a cubemap texture from a single (stitched) image file of any type
<LI>sped up the image resizing code
</UL>
<LI>August 24, 2007 - updated the documentation examples (at the bottom of this page)
<LI>August 22, 2007
<UL>
<LI>can load cube maps (needs serious testing)
<LI>can compress 1- or 2-channel images to DXT1/5
<LI>fixed some malloc() casts
<LI>fixed C++ style comments
<LI>fixed includes to compile under *nix or Mac (hopefully, needs testing...any volunteers?)
</UL>
<LI>August 16, 2007
<UL>
<LI>Will now downsize the image if necessary to fit GL_MAX_TEXTURE_SIZE
<LI>added SOIL_create_OGL_texture() to upload raw image data that isn't from an image file
</UL>
<LI>August 14, 2007 (PM) - Can now load indexed TGA
<LI>August 14, 2007 (AM)
<UL>
<LI>Updated to stb_image 0.97
<LI>added result messages
<LI>can now decompress DDS files (DXT1/2/3/4/5)
</UL>
<LI>August 11, 2007 - MIPmaps can now handle non-square textures
<LI>August 7, 2007
<UL>
<LI>Can directly upload DXT1/3/5 DDS files (with or w/o MIPmaps)
<LI>can compress any image to DXT1/5 (using a new & fast & simple compression scheme) and upload
<LI>can save as DDS
</UL>
<LI>July 31, 2007 - added compressing to DXT and flipping about Y
<LI>July 30, 2007 - initial release
</UL>
<BR>
<BR>
<PRE STYLE="text-align: center">back to
<A HREF="http://www.lonesock.net/">www.lonesock.net</A></PRE>
</BODY>
</HTML>