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.