PNG loader library for OpenGL v1.41 (20/10/99)

Ben Wyatt ben@wyatt100.freeserve.co.uk

Introduction

This is a library for OpenGL to load PNG graphics files as an OpenGL texture as easily as possible. It also has a number of options for generating the alpha channel and mipmaps. It is implemented using modified versions of the LibPNG 1.0.2 and ZLib 1.1.3 libraries.

Installation for Visual C++

Copy glpng.h to your include/gl folder and glpng.lib to your lib folder. Then just do #include <GL/glpng.h> and with a bit of luck, Visual C++ will automatically link with glpng.lib.

Installation for Any Other Compiler

Copy glpng.h to your include/gl folder. Then you'll have to build the library yourself with the included source code. Included are makefiles for Linux and SGI, thanks to Mark B. Allan. If you need to modify the source code to make it work on your system, please get in contact so I can make future versions compatible.

Compiling with LibPNG or ZLib

If you are using LibPNG or ZLib in your project there may be problems if you link with the glpng library. To solve this, include glpng.c in your project and, if you're using Visual C++, modify glpng.h to not automatically link with glpng.lib.

OpenGL DLL Dynamic Loading using glsetup

To use glpng with glsetup, include glpng.c, LibPNG and ZLib in your project. In glpng.c, change #include <GL/gl.h> to include the glsetup include and modify glpng.h to not automatically link with glpng.lib.

Functions

• pngLoad
• pngLoadF
• pngBind
• pngBindF
• pngSetStencil
• pngSetAlphaCallback
• pngSetViewingGamma
• pngLoadRaw
• pngLoadRawF

success = pngLoad(filename, mipmap, trans, info)

filename	Filename of PNG file, including ".png"
mipmap	Mipmapping parameter: 0 or PNG_NOMIPMAP if no mipmap or for the base mipmap level 1,2,3... for mipmap detail level PNG_BUILDMIPMAPS to call a clone of gluBuild2DMipmaps (box filter) PNG_SIMPLEMIPMAPS to generate mipmaps without filtering (uses upper-left of each 2x2 box)
trans	Transparency setting: PNG_ALPHA to use alpha channel in PNG file, if there is one PNG_SOLID for no transparency PNG_STENCIL to set pixels of a certain value to alpha 0, otherwise 1 (see pngSetStencil) PNG_BLEND1 to set alpha to r+g+b PNG_BLEND2 to set alpha to (r+g+b)/2 PNG_BLEND3 to set alpha to (r+g+b)/3 PNG_BLEND4 to set alpha to r2+g2+b2 PNG_BLEND5 to set alpha to (r2+g2+b2)/2 PNG_BLEND6 to set alpha to (r2+g2+b2)/3 PNG_BLEND7 to set alpha to (r2+g2+b2)/4 PNG_BLEND8 to set alpha to sqrt(r2+g2+b2) PNG_CALLBACK to use the callback function defined by pngSetAlphaCallback.
info	Pointer to a pngInfo structure to store texture info or NULL if you don't care. The pngInfo fields are: Width - width of the original image in pixels Height - height of the original image in pixels Depth - depth of the original image, where colours = 2Depth Alpha - the number of bits used for the alpha channel (0 if no alpha channel)

Loads a PNG file and calls glTexImage2D with appropriate parameters. The texture will be resized if the dimensions are not powers of 2 or over the maximum texture size. Should be able to load all colour depths (except 64-bit) and alpha channels if available. It converts them to an appropriate format and gives them to glTexImage2D. The OpenGL paletted texture extension is used if available.

Returns 1 on success or 0 if file could not be loaded.

success = pngLoadF(file, mipmap, trans, info)

file	FILE opened with fopen("something.png", "rb")

This is used to load a PNG from an already opened file. Handy if you want to batch all your data and textures into one big data file.

id = pngBind(filename, mipmap, trans, info, wrapst, minfilter, magfilter)
id = pngBindF(file, mipmap, trans, info, wrapst, minfilter, magfilter)

wrapst	GL_CLAMP or GL_REPEAT (look up glTexParameter)
minfilter	Minification function for filtering (look up glTexParameter)
magfilter	Magnification function for filtering (look up glTexParamter)

Automates the process further - loads a PNG file, sets the OpenGL parameters, binds it to an OpenGL texture and returns it's ID, or 0 if the file couldn't be loaded.

pngSetStencil(red, green, blue)

red,green,blue

The colour to stencil out when using the PNG_STENCIL option

This selects the colour to stencil out when using PNG_STENCIL. The parameters are 0 to 255. By default the colour is 0,0,0 (pure black).

pngSetAlphaCallback(function)

function

Pointer to a function taking three unsigned char parameters (red, green, blue) and returning an unsigned char (alpha)

This sets the function to be called when using PNG_CALLBACK. During the alpha channel generation process, this function will be called for every pixel, with the appropriate RGB values, and will use the result for the alpha value. The RGB and alpha values all range from 0 to 255. The default callback function simply returns 255.

pngSetViewingGamma(gamma)

gamma

New gamma correction value

By default, gamma correction is set to 1.0 for Windows, 1.7 for SGI and 1.45 for Macs. If the VIEWING_GAMMA environmental variable is set, that is used instead. You can override both of these values using pngSetViewingGamma().

success = pngLoadRaw(filename, rawinfo)
success = pngLoadRawF(file, rawinfo)

rawinfo

Pointer to a pngRawInfo structure in which to store the PNG data. The pngRawInfo has these fields: Width, Height, Depth, Alpha - as in pngInfo Components - number of colour components (1, 2, 3 or 4) Data - pointer to image data stored as RGBRGB... or RGBARGBA... or indices to the palette table. Must be freed manually using free() Palette - pointer to palette table stored as RGBRGB... or RGBARGBA... Will be NULL if there is no palette table. Must be freed manually using free()

Examples

Here's an example of pngLoad(), to load "Texture.png" with nearest filter, clamping on and no mipmaps or alpha channels...

pngInfo info;
GLuint id;

glGenTextures(1, &id);
glBindTexture(GL_TEXTURE_2D, id);

glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP);

if (pngLoad("Texture.png", PNG_NOMIPMAP, PNG_SOLID, &info)) {
   puts("Loaded Texture.png with resounding success");
   printf("Size=%i,%i Depth=%i Alpha=%i\n", info.Width, info.Height, info.Depth, info.Alpha);
}
else {
   puts("Can't load Texture.png");
   exit(1);
}

And here's an example to load the same texture with the same options using pngBind()...

pngInfo info;
GLuint id = pngBind("Texture.png", PNG_NOMIPMAP, PNG_SOLID, &info, GL_CLAMP, GL_NEAREST, GL_NEAREST);

if (id != 0) {
   puts("Loaded Texture.png with resounding success");
   printf("Size=%i,%i Depth=%i Alpha=%i\n", info.Width, info.Height, info.Depth, info.Alpha);
}
else {
   puts("Can't load Texture.png");
   exit(1);
}

If those two examples don't make sense, try the included full source example (which needs GLUT).

Bugs

• Some paletted PNGs, that aren't 256 colours, cause a crash. Might be a bug in LibPNG, but then again, it could be a bug in glpng.
• 64-bit PNGs can't be loaded (missing LibPNG feature as far as I can tell).
• The paletted textures extension doesn't work on the current 3dfx OpenGL beta driver - this is checked for and ignored. The paletted textures extension is enabled on the more recent 3dfx Quake3 drivers but this has not been tested.

Possible Future Developments

• Better attempts could be made to find the optimal texture format for OpenGL. At the moment, it converts everything to 24 or 32 bit, or uses the paletted texture extension in certain (easy to handle) cases.
• Other mipmap generating algorithms could be implemented (wavelet stuff?). Source donations are welcome.
• Saving the frame buffer to a PNG file.
• Support for GL_INTENSITY, GL_LUMINANCE_ALPHA and others.

History

Get the latest version from http://www.wyatt100.freeserve.co.uk/download.htm