uPNG -- derived from LodePNG version 20100808

Copying

Copyright (c) 2005-2010 Lode Vandevenne Copyright (c) 2010 Sean Middleditch

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

Features

uPNG supports loading and decoding PNG images into a simple byte buffer, suitable for passing directly to OpenGL as texture data.

uPNG does NOT support interlaced images, paletted images, and fixed-transparency. Checksums are NOT verified and corrupt image data may be undetected.

It DOES support RGB, RGBA, greyscale, and greyscale-with-alpha images. RGB and RGBA are currently only supported in 8-bit color depths, and greyscale images are supported in either 1-, 2-, 4-, or 8-bit color depths.

WARNING: the source project that uPNG is derived from, LodePNG, did not have the cleanest or best documented code. Several potential buffer overflows in the original source have been fixed in uPNG, but there may be more. Do NOT use uPNG to load data from untrusted sources, e.g. the Web. Doing so may open a remotely exploitable buffer overflow attack in your application.

Installation

Copy the upng.c and upng.h files into your project, and add them to your build system. upng.c will compile as C++ if necessary.

Usage

To load a PNG, you must create an upng_t instance, load the raw PNG into the decoder, and then you can query the upng_t for image properties and the decoded image buffer.

upng_t* upng;

upng = upng_new_from_file("image.png"); if (upng != NULL) { upng_decode(upng); if (upng_get_error(upng) == UPNG_EOK) { /* do stuff with image */ }

upng_free(upng);

}

You can load a PNG either from an in-memory buffer of bytes or from a file specified by file path.

upng_new_from_bytes(const unsigned char*, unsigned long length) upng_new_from_file(const char*)

Once an upng_t object is created, you can read just its header properties, decode the entire file, and release its resources.

upng_header(upng_t*) Reads just the header, sets image properties upng_decode(upng_t*) Decodes image data upng_free(upng_t*) Frees the resources attached to a upng_t object

The query functions are:

upng_get_width(upng_t*) Returns width of image in pixels upng_get_height(upng_t*) Returns height of image in pixels upng_get_size(upng_t*) Returns the total size of the image buffer in bytes upng_get_bpp(upng_t*) Returns the number of bits per pixel (e.g., 32 for 8-bit RGBA) upng_get_bitdepth(upng_t*) Returns the number of bits per component (e.g., 8 for 8-bit RGBA) upng_get_pixelsize(upng_t*) Returns the number of bytes per pixel (e.g., 4 for 8-bit RGBA) upng_get_components(upng_t*) Returns the number of components per pixel (e.g., 4 for 8-bit RGBA) upng_get_format(upng_t*) Returns the format of the image buffer (see below) upng_get_buffer(upng_t*) Returns a pointer to the image buffer

Additionally, for error handling, you can use:

upng_get_error(upng_t*) Returns the error state of the upng object (UPNG_EOK means no error) upng_get_error_line(upng_t*) Returns the line in the upng.c file where the error state was set

The formats supported are:

UPNG_RGB8 24-bit RGB UPNG_RGB16 48-bit RGB UPNG_RGBA8 32-bit RGBA UPNG_RGBA16 64-bit RGBA UPNG_LUMINANCE8 8-bit Greyscale UPNG_LUMINANCEA8 8-bit Greyscale w/ 8-bit Alpha

Possible error states are:

UPNG_EOK No error (success) UPNG_ENOMEM Out of memory UPNG_ENOTFOUND Resource not found UPNG_ENOTPNG Invalid file header (not a PNG image) UPNG_EMALFORMED PNG image data does not follow spec and is malformed UPNG_EUNSUPPORTED PNG image data is well-formed but not supported by uPNG

TODO

• Audit the code (particularly the Huffman decoder) for buffer overflows. Make sure uPNG is safe to use even with image data from untrusted sources.

• Make the decompressor work in a streaming/buffered manner, so that we don't need to stitch together the PNG IDATA chunks before decompressing, shaving off one unnecessary allocation.

• Update the unfiltering code to work on the decompressed image buffer, rather than needing a separate output buffer. The removal of the Adam7 de-interlacing support makes this easier. Removes another unnecessary allocation.

• Update the decoder API to work in a stream/buffered manner, so files can be read without needing to allocate a temporary buffer. This removes yet another unnecessary allocation.

• Update the decoder API to allow the user to provide an output buffer, so that PNG images can be decoded directly to mapped texture memory. Removes the need for the last unnecessary allocation.

• Test that greyscale images with less than 8-bits of depth actually work, fix or remove if they do not.

• Provide optional format conversion (as an extension to byte swizzling) to convert input PNGs in one format to one of a (limited) set of target output formats commonly used for texturing.

• Provide floating-point conversion, at least for 16-bit source images, for HDR textures.

• Provide vertical flipping of decoded image data for APIs that prefer textures with an origin in the lower-left instead of upper-left.