SOIL: new lightweight image loading lib

lonesock · 2010-05-28T18:12:52

Hi, All. This is an announcement, but I think it fits better in this forum. If I'm wrong, feel free to move it [8^) I've been looking for a tiny image loading library for some hobby OpenGL game projects I'm working on, but never really found exactly what I wanted. Then I found Sean Barrett's awesome C code for loading BMP/PNG/JPG files (here). I took that, added TGA loading support (except for indexed TGA images), wrapped some common functions like upsizing to power-of-two sizes, MIPmap generation, pre-multiplying alpha, etc. all into a single function call for easy loading of textures into OpenGL. Presenting the Simple OpenGL Image Library (yes, I'm sorry SOIL is such a lame acronym [8^) Features: Loads PNG, JPG, TGA, BMP, DDS (a subset of each type) Saves TGA, BMP, DDS Loads an image file directly into an OpenGL texture Can automatically rescale the image to the next largest power-of-two size Can automatically create MIPmaps Can multiply alpha on load (for more correct blending / compositing) Can flip the image vertically Can compress to DXT1 or DXT5 (if EXT_texture_compression_s3tc is available) Will downsize the image if necessary to fit GL_MAX_TEXTURE_SIZE No external dependencies Tiny Public Domain If anybody is willing to give some feedback, I'd really appreciate it (I'm keeping this a C project, and my C skills are extremely rusty). Feature requests are also welcome. [edited to add new features] [Edited by - lonesock on August 16, 2007 11:59:53 AM]

Engines and Middleware Programming

Started by lonesock July 30, 2007 11:43 PM

129 comments, last by GenPFault 13 years, 10 months ago

lonesock

808

Author

October 05, 2007 07:09 PM

A new update is out:
* fixed a rare memory error in up_scale_image (thanks Pete!)
* sped up the up_scale_image function
* added SOIL_FLAG_NTSC_SAFE_RGB to SOIL, which causes SOIL to scale the RGB values from [0,255] to [16,235], the "safe range" for NTSC output devices (a.k.a. most US TV sets). Alpha levels remain untouched.

I plan on trying to optimize my MIPmap generation code, as that seems to be the most common bottleneck now. I will also be playing with a few different programming languages to make sure they can use SOIL (thanks for the inspiration, Merick Zero!)

lonesockPiranha are people too.www.lonesock.net SOIL: Simple OpenGL Image LibraryMovies I've mocked: "The Core", "The Mummy", "Tale of Despereaux"

thelovegoose

101

October 05, 2007 08:36 PM

oops

[Edited by - thelovegoose on October 5, 2007 9:36:38 PM]

Merick Zero

151

October 15, 2007 11:54 AM

I've got a problem using this in FreeBasic. First, if I make multiple calls to SOIL_load_OGL_texture using the SOIL_CREATE_NEW_ID flag, all of them end up returning 0 for the texture id. Aside from the fact that it just keeps over-writing the same texture with the new image, 0 is also what gets returned on an error

However, if I do specify a number for the texture id it works fine.

lonesock

808

Author

October 17, 2007 11:35 AM

I will look into this, thanks for the info.

*Edited to load 2 images*

OK, I have it working with the following lines:

dim shared g_texture as GLuint
dim shared g_texture2 as GLuint
g_texture = SOIL_load_OGL_texture( "terrain.bmp", SOIL_LOAD_AUTO, SOIL_CREATE_NEW_ID, SOIL_FLAG_MIPMAPS )
g_texture2 = SOIL_load_OGL_texture( "mars-ter.png", SOIL_LOAD_AUTO, SOIL_CREATE_NEW_ID, SOIL_FLAG_MIPMAPS )

And here is the header file (I re-ran SWIG with the latest version, so make sure you are using the latest libSOIL.a file); SOIL.bi

''''''	Jonathan Dummer''	Simple OpenGL Image Library''	MIT License''''	I'm using Sean's Tool Box image loader as a base:''	http://www.nothings.org/''''	Note: header translated with help of SWIG FB wrapper''	Check the SOIL.h file for more information''#ifndef __SOIL_bi__#define __SOIL_bi__#inclib "SOIL"enum 	SOIL_LOAD_AUTO = 0	SOIL_LOAD_L = 1	SOIL_LOAD_LA = 2	SOIL_LOAD_RGB = 3	SOIL_LOAD_RGBA = 4end enumenum 	SOIL_CREATE_NEW_ID = 0end enumenum 	SOIL_FLAG_POWER_OF_TWO = 1	SOIL_FLAG_MIPMAPS = 2	SOIL_FLAG_TEXTURE_REPEATS = 4	SOIL_FLAG_MULTIPLY_ALPHA = 8	SOIL_FLAG_INVERT_Y = 16	SOIL_FLAG_COMPRESS_TO_DXT = 32	SOIL_FLAG_DDS_LOAD_DIRECT = 64	SOIL_FLAG_NTSC_SAFE_RGB = 128end enumenum 	SOIL_SAVE_TYPE_TGA = 0	SOIL_SAVE_TYPE_BMP = 1	SOIL_SAVE_TYPE_DDS = 2end enumconst SOIL_DDS_CUBEMAP_FACE_ORDER = "EWUDNS"declare function SOIL_load_OGL_texture cdecl alias "SOIL_load_OGL_texture" (byval filename as zstring ptr, byval force_channels as integer, byval reuse_texture_ID as uinteger, byval flags as uinteger) as uintegerdeclare function SOIL_load_OGL_cubemap cdecl alias "SOIL_load_OGL_cubemap" (byval x_pos_file as zstring ptr, byval x_neg_file as zstring ptr, byval y_pos_file as zstring ptr, byval y_neg_file as zstring ptr, byval z_pos_file as zstring ptr, byval z_neg_file as zstring ptr, byval force_channels as integer, byval reuse_texture_ID as uinteger, byval flags as uinteger) as uintegerdeclare function SOIL_load_OGL_single_cubemap cdecl alias "SOIL_load_OGL_single_cubemap" (byval filename as zstring ptr, byval face_order as zstring ptr, byval force_channels as integer, byval reuse_texture_ID as uinteger, byval flags as uinteger) as uintegerdeclare function SOIL_load_OGL_texture_from_memory cdecl alias "SOIL_load_OGL_texture_from_memory" (byval buffer as ubyte ptr, byval buffer_length as integer, byval force_channels as integer, byval reuse_texture_ID as uinteger, byval flags as uinteger) as uintegerdeclare function SOIL_load_OGL_cubemap_from_memory cdecl alias "SOIL_load_OGL_cubemap_from_memory" (byval x_pos_buffer as ubyte ptr, byval x_pos_buffer_length as integer, byval x_neg_buffer as ubyte ptr, byval x_neg_buffer_length as integer, byval y_pos_buffer as ubyte ptr, byval y_pos_buffer_length as integer, byval y_neg_buffer as ubyte ptr, byval y_neg_buffer_length as integer, byval z_pos_buffer as ubyte ptr, byval z_pos_buffer_length as integer, byval z_neg_buffer as ubyte ptr, byval z_neg_buffer_length as integer, byval force_channels as integer, byval reuse_texture_ID as uinteger, byval flags as uinteger) as uintegerdeclare function SOIL_load_OGL_single_cubemap_from_memory cdecl alias "SOIL_load_OGL_single_cubemap_from_memory" (byval buffer as ubyte ptr, byval buffer_length as integer, byval face_order as zstring ptr, byval force_channels as integer, byval reuse_texture_ID as uinteger, byval flags as uinteger) as uintegerdeclare function SOIL_create_OGL_texture cdecl alias "SOIL_create_OGL_texture" (byval data as ubyte ptr, byval width as integer, byval height as integer, byval channels as integer, byval reuse_texture_ID as uinteger, byval flags as uinteger) as uintegerdeclare function SOIL_create_OGL_single_cubemap cdecl alias "SOIL_create_OGL_single_cubemap" (byval data as ubyte ptr, byval width as integer, byval height as integer, byval channels as integer, byval face_order as zstring ptr, byval reuse_texture_ID as uinteger, byval flags as uinteger) as uintegerdeclare function SOIL_save_screenshot cdecl alias "SOIL_save_screenshot" (byval filename as zstring ptr, byval image_type as integer, byval x as integer, byval y as integer, byval width as integer, byval height as integer) as integerdeclare function SOIL_load_image cdecl alias "SOIL_load_image" (byval filename as zstring ptr, byval width as integer ptr, byval height as integer ptr, byval channels as integer ptr, byval force_channels as integer) as ubyte ptrdeclare function SOIL_load_image_from_memory cdecl alias "SOIL_load_image_from_memory" (byval buffer as ubyte ptr, byval buffer_length as integer, byval width as integer ptr, byval height as integer ptr, byval channels as integer ptr, byval force_channels as integer) as ubyte ptrdeclare function SOIL_save_image cdecl alias "SOIL_save_image" (byval filename as zstring ptr, byval image_type as integer, byval width as integer, byval height as integer, byval channels as integer, byval data as ubyte ptr) as integerdeclare sub SOIL_free_image_data cdecl alias "SOIL_free_image_data" (byval img_data as ubyte ptr)declare function SOIL_last_result cdecl alias "SOIL_last_result" () as zstring ptr#endif

Note that returning 0 signifies an error, as you mentioned, because OpenGL will return a 0 if it fails to generate a texture ID. Binding a 0 as your texture ID is now (I believe) undefined.

[Edited by - lonesock on October 17, 2007 1:35:44 PM]

lonesockPiranha are people too.www.lonesock.net SOIL: Simple OpenGL Image LibraryMovies I've mocked: "The Core", "The Mummy", "Tale of Despereaux"

Merick Zero

151

October 17, 2007 05:03 PM

Which version of the FreeBasic compiler did you test it with? With 0.18 r2, this code:

#include once "GL/gl.bi"#include once "soil.bi"dim shared g_texture as GLuintdim shared g_texture2 as GLuintscreen 18glGenLists 10g_texture = SOIL_load_OGL_texture( "ball.png", SOIL_LOAD_AUTO, SOIL_CREATE_NEW_ID, SOIL_FLAG_MIPMAPS )print g_textureprint *SOIL_last_resultg_texture2 = SOIL_load_OGL_texture( "mc.png", SOIL_LOAD_AUTO, SOIL_CREATE_NEW_ID, SOIL_FLAG_MIPMAPS )print g_texture2print *SOIL_last_resultsleep

gives me this output:

0
Image loaded as an OpenGL texture

0
Image loaded as an OpenGL texture

Just in case, I did re-download the .zip from your link, but the libsoil.a in the archive is the same as the one I was already using.

lonesock

808

Author

October 18, 2007 04:05 PM

Quote:Original post by Merick Zero
gives me this output:
0
Image loaded as an OpenGL texture

Well, the 0 is most likely because there is no OpenGL context yet. If I understand the FreeBasic docs correctly, you need to say "screen 18,16,,&h02" or something similar to actually initialize the OpenGL driver. I've had trouble doing just that simple example, though...it seems that if you don't actually display anything then the context is not created. However when I drop the SOIL test code into already working OpenGL examples (provided with the FB compiler) it has worked.

The "Image loaded as an OpenGL texture" part means that SOIL doesn't detect this class of error. I will get working on that.

lonesockPiranha are people too.www.lonesock.net SOIL: Simple OpenGL Image LibraryMovies I've mocked: "The Core", "The Mummy", "Tale of Despereaux"

Merick Zero

151

October 18, 2007 08:28 PM

Ah, so that's what was wrong

#include once "fbgfx.bi"#include once "GL/gl.bi"#include once "soil.bi"dim shared g_texture as GLuintdim shared g_texture2 as GLuintscreenres 648,480,32, 1, FB.GFX_OPENGL, FB.GFX_MULTISAMPLEglGenLists 10open cons for output as #1g_texture = SOIL_load_OGL_texture( "ball.png", SOIL_LOAD_AUTO, SOIL_CREATE_NEW_ID, SOIL_FLAG_MIPMAPS )print #1, g_textureprint #1, *SOIL_last_resultg_texture2 = SOIL_load_OGL_texture( "mc.png", SOIL_LOAD_AUTO, SOIL_CREATE_NEW_ID, SOIL_FLAG_MIPMAPS )print #1, g_texture2print #1, *SOIL_last_resultwhile not multikey(FB.SC_ESCAPE)	flipwend

"fbgfx.bi" puts the constants for the internal graphics and keyboard scancodes into the FB namespace

Dancho

151

October 22, 2007 03:38 PM

heya,
Im testing your image loading libery and having problem with this little snippet:

#include <soil.h>#include <glfw.h>int main(int argc,char *argv[]){	GLuint tex_2d;		tex_2d=SOIL_load_OGL_texture("somepicname.png",SOIL_LOAD_AUTO,SOIL_CREATE_NEW_ID,		SOIL_FLAG_MIPMAPS | SOIL_FLAG_INVERT_Y | SOIL_FLAG_NTSC_SAFE_RGB | SOIL_FLAG_COMPRESS_TO_DXT);	return 0;}

and these are errors:

error LNK2005: _SOIL_DDS_CUBEMAP_FACE_ORDER already defined in main.obj

fatal error LNK1169: one or more multiply defined symbols found

libs (glfw,soil,opengl32,glu32) are linked staticly in console project VC++2005EE and compiled as C language,

thanks for your time,
Dancho

lonesock

808

Author

October 23, 2007 12:07 AM

@Dancho: Thanks for testing SOIL! I'm not sure why that error occurs, but I have a suspicion. I have 2k5 EE at home, so I will test this within a few days. In the mean time you may be able to get it to compile and run by commenting out the offending lines (you can pass in "EWUDNS" instead if needed):

/*
const char SOIL_DDS_CUBEMAP_FACE_ORDER[] =
{ 'E', 'W', 'U', 'D', 'N', 'S' };
*/

BTW, in that snippet SOIL_load_OGL_texture will have trouble because there is no OpenGL context. You will need to call glfwInit() and glfwOpenWindow(...) before SOIL can upload OpenGL textures. It can still load them just fine for other purposes (via SOIL_load_image(), etc.).

Thanks again for testing SOIL and for the feedback!