What is TinyImageLoader?

TinyImageLoader (TIL) is an image loading library written in C++. It started because I wanted to load images on Windows Mobile. So I downloaded the FreeImage source and started to include it in my project. Then I noticed it was over 2 MB of static libraries! On a platform that has only 64 to spare! I started to look at alternatives. DevIL didn't work either. Finally, I stumbled on stb_image.c.

I was intrigued. What if I rewrote stb_image.c to not only look better, but support more image formats as well?

From that followed TinyImageLoader. In its most optimized form, TIL is a mere 116 kB.

EDIT REGARDING STB_IMAGE: Mr. Barrett noted below that I did not credit him for his work. An oversight on my part! I have since corrected this. The SVN version of TILImagePNG.cpp has a credit section for his work on stb_image.c and will be included in future versions of TinyImageLoader.

What does TIL support?

TIL supports: PNG, BMP, GIF, ICO and TGA. It also supports APNG (animated PNG) and animated GIF.

What can you do with TIL?

All you can do is load images and convert them to the correct color depth. For example, if you're working on Windows Mobile, you will be using 16-bit color. You would load images like this:


til::Image* load = til::TIL_Load("texture.png", TIL_FILE_ADDWORKINGDIR | TIL_DEPTH_R5G6B5);

How would I use TIL to load a texture?

You can load a texture like so:

// Initialize TinyImageLoader

til::TIL_Init();

// [ more code here ]

// Load an image
// Note: OpenGL reverses the pixel components
// TIL_DEPTH_A8B8G8R8 = GL_RGBA

til::Image* load = til::TIL_Load("media\\PNG\\avatar.png", TIL_FILE_ADDWORKINGDIR | TIL_DEPTH_A8B8G8R8);

// Load the pixel data into the texture

glEnable(GL_TEXTURE_2D);
glGenTextures(1, &g_Texture);
glBindTexture(GL_TEXTURE_2D, g_Texture);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_REPEAT);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_REPEAT);
glTexImage2D(
GL_TEXTURE_2D, 0, GL_RGBA,
load->GetWidth(), load->GetHeight(),
0,
GL_RGBA, GL_UNSIGNED_BYTE, load->GetPixels()
);
glBindTexture(GL_TEXTURE_2D, 0);</pre>

This example can be found in the examples solution provided with TinyImageLoader.

How well documented is TIL?

As of version 1.6.0, TinyImageLoader is fully documented. The documentation can be found in the docs folder in the SDK folder. An example of an image viewer using OpenGL is provided.

I want to use TIL in my commercial project. Is that allowed?

TinyImageLoader is free software licensed under the MIT license. This means you can do whatever you want with the code (redistribute, change, use) as long as you attribute the project owner.

I found an image that doesn't load correctly. What should I do?

E-mail me at knight666 (at) gmail (dot) com with the code you were using to load the image and the offending image. You can also try fixing it yourself, using the latest source found on the SVN. If you have fixed it, let me know! I will review your patch and hopefully include it in the next release.

Project home: http://code.google.c...inyimageloader/

Stable release: http://code.google.com/p/tinyimageloader/downloads/detail?name=TinyImageLoader%201.6.3.zip

Changes in 1.6.0

• Fixed all memory leaks.
• Added documentation
• Added DDS loader (DXT1 and DXT5 support)
• Added FileStream abstraction (check the zip loading example)
• Added detailed tutorial
• Fixed tons of bugs

Changes in 1.6.1

• Framework project pointing to wrong GLEW library (glew32_x86.lib instead of the standard glew32.lib)
• Missing third-party libraries page in the documentation

Changes in 1.6.2

• Fixed a serious heap corruption bug caused by til::TIL_AddDebug
• Fixed a serious heap corruption bug caused by til::TIL_AddError
• Fixed memory leak in til::FileStreamStd - path string was not deleted
• Fixed memory leak in til::TIL_Load - FileStream handle was not deleted
• Fixed bug in til::TIL_Load - FileStream was being closed twice
• Fixed memory leaks in til::ImageICO

Changes in 1.6.3

• Added til::TIL_Release function, which releases a handle
• Added TIL_TARGET_DEVEL target for developers
• Removed unnecessary includes (e.g. windows.h, stdlib.h, etc.)
• Fixed a bug where til::TIL_ShutDown could cause a crash by deleting an uninitialized variable

wow this is great and exactly what I've been looking for, I'm going to use this for my next mobile project.

To be fair, instead of using a project forked from stb_image.c, you could just use stb_image.c itself.

Advantages compared to TIL:

• also supports JPG, PSD, HDR
  
• already ported and tested on many platforms (of both endianness)
  
• easy to integrate in a project on any platform since it's just one file so you don't need to worry about makefiles/projects/solutions etc.
  
• usable from C
  
• all contributors are fully credited in the source, so you can feel morally good about that1
  
• you can easily update when there are future improvements to stb_image, such as new image formats, optimizations, memory-usage reduction; I imagine the latter two at least are unlikely to make it into TIL
  

Disadvantages compared to TIL:

• no support for animated PNG, animated GIF
  
• no 565 support
  
• no support for whatever else TIL added to stb_image
  

Not actually a disadvantage compared to TIL:

• stb_image.c is not spaghetti code. It's just dense C-style code arranged in a single file. "Not object-oriented" doesn't mean "spaghetti". Plus who cares what it looks like, it's an opaque library. You don't need to look at the source.
  

1 I placed stb_image in the public domain for the convenience of users of the library, i.e. people who are actually loading images, not for people who wanted to fork the project (that's an unavoidable side-effect). I would like to be credited and I think I have a moral right to be credited, but I think it's the sort of thing that is best handled by criticizing people who don't credit, not by bringing the (ludicrously expensive) legal system to bear, and I use the public domain "license" to make this overt (so everybody knows up front the legal system is irrelevant). Again, Quinten Lansu has every legal right to remove my name from his project despite the fact that, e.g., 90% of the PNG decoder is mine. I don't want to cause internet dorama over this; I just want to make explicit my stance on the moral vs legal issues at play, since readers will be using (as far as I can tell) plenty of my code.

Quote:Original post by nothings
To be fair, instead of using a project forked from stb_image.c, you could just use stb_image.c itself.

Advantages compared to TIL:

• also supports JPG, PSD, HDR
  
• already ported and tested on many platforms (of both endianness)
  
• easy to integrate in a project on any platform since it's just one file so you don't need to worry about makefiles/projects/solutions etc.
  
• usable from C
  
• all contributors are fully credited in the source, so you can feel morally good about that1
  
• you can easily update when there are future improvements to stb_image, such as new image formats, optimizations, memory-usage reduction; I imagine the latter two at least are unlikely to make it into TIL
  

Disadvantages compared to TIL:

• no support for animated PNG, animated GIF
  
• no 565 support
  
• no support for whatever else TIL added to stb_image
  

Not actually a disadvantage compared to TIL:

• stb_image.c is not spaghetti code. It's just dense C-style code arranged in a single file. "Not object-oriented" doesn't mean "spaghetti". Plus who cares what it looks like, it's an opaque library. You don't need to look at the source.
  

1 I placed stb_image in the public domain for the convenience of users of the library, i.e. people who are actually loading images, not for people who wanted to fork the project (that's an unavoidable side-effect). I would like to be credited and I think I have a moral right to be credited, but I think it's the sort of thing that is best handled by criticizing people who don't credit, not by bringing the (ludicrously expensive) legal system to bear, and I use the public domain "license" to make this overt (so everybody knows up front the legal system is irrelevant). Again, Quinten Lansu has every legal right to remove my name from his project despite the fact that, e.g., 90% of the PNG decoder is mine. I don't want to cause internet dorama over this; I just want to make explicit my stance on the moral vs legal issues at play, since readers will be using (as far as I can tell) plenty of my code.

I'm very sorry, Mr. Nothings. My original wording was poor. I simply copy pasted this post from our internal school forum to a forum intended for a far broader audience.

I respect you and hold your code in the highest regard. I should have credited you for your work and I most certainly will. I learned a lot by looking at your implementation of the PNG image format.

To defend my library:

• Unlike stb_image, it is entirely modular. You can turn off image formats you don't need with a single define (TIL_FORMATS).
  
• You can easily add new image formats by overloading til::Image and implementing its members.
  
• I could not have extended stb_image to include animated PNG because I could not grasp what it was doing. This may be a personal flaw, but I was annoyed to find one function nesting another on multiple levels.
  

Is it alright to continue using your PNG loader (*with* proper credits) or would you like me to remove it entirely?

Quote:Original post by knight666
To defend my library:

You don't need to defend it! There's nothing wrong with it!

Quote:

• Unlike stb_image, it is entirely modular. You can turn off image formats you don't need with a single define (TIL_FORMATS).
  
• You can easily add new image formats by overloading til::Image and implementing its members.
  
• I could not have extended stb_image to include animated PNG because I could not grasp what it was doing. This may be a personal flaw, but I was annoyed to find one function nesting another on multiple levels.
  

1. If anybody had asked for the first item, I would have added it to stb_image. (It's already present for HDR, I think.)

2. It's easy to add new formats to stb_image, it just requires installing function pointers, since that's how you do it in C.

3. Well, you managed to grasp it enough to alter it and add it in TIL, but I think I know what you mean.

Quote:Is it alright to continue using your PNG loader (*with* proper credits) or would you like me to remove it entirely?

Of course it's alright. It's just it would be nice if there was credit in the source (I don't care about the docs or the binary-only releases), that's all. The full credits for stb_image are pretty long, so if you don't want to credit them all, credit me by name and say the full credits are available in stb_image.c and give a link to that. If you actually only used the PNG stuff then I guess you only need to credit me. (I didn't look at your TGA or other stuff.)

I'm glad we managed to talk things out. :)

I have since added the following notice to TILImagePNG.cpp (available on SVN):

Quote:/*

The following PNG loader is entirely based on the works of Sean Barrett
a.k.a. nothings. You can download the original stb_image.c from his website
at http://www.nothings.org/stb_image.c

stb_image is a legendary compact file loader that implements multiple file
formats in a single C file. It does so in an opague, but easy to use way.

The original idea for TinyImageLoader came from reimplementing stb_image.c
in such a way that it would be readable to me. When I was done I started
implementing other formats as well. Without stb_image, no TinyImageLoader.

What I changed:
* Support for different color depths
* Added Animated PNG support

Everything else is Mr. Barrett's code implemented in a different manner.

-knight666

*/

http://tinyimageloader.googlecode.com/svn/trunk/src/TILImagePNG.cpp

Thanks! I hope that didn't cause undue stress in the interim.

I have released a new version. TinyImageLoader now has documentation, no memory leaks and support for DDS. Proper credits have been given where credit was due.

Project home: http://code.google.com/p/tinyimageloader/
Direct link: http://code.google.com/p/tinyimageloader/downloads/detail?name=TinyImageLoader%201.6.3.zip