PNGDIB - a mini DIB-PNG conversion library for Win32
By Jason Summers  <jason1@pobox.com>
Version 2.2.0, Apr. 2002
Web site: http://pobox.com/~jason1/pngdib/
Note: version 2.2.2 is out which fixes a memory freeing bug
(presently AbiWord defaults to libpng 1.2.3)


This software is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.

Permission is hereby granted to use, copy, modify, and distribute this
source code for any purpose, without fee.


The pngdib.c file contains two functions that convert between PNG images
and Windows Device Independent Bitmaps (DIBs). PNGDIB is designed to be
quick and easy to use, but it does not attempt to support every feature
that one might want. If you wish use the PNG format to its full
capabilities, you'll need to use libpng directly, or program our own
extensions to PNGDIB.

REQUIREMENTS

* zlib  <http://www.info-zip.org/pub/infozip/zlib/>
Tested with v1.1.4; other versions probably also work.

* libpng  <http://www.libpng.org/pub/png/>
Version 1.2.2beta5 or higher recommended. Most versions from about 1.0.5
on will probably work, but they do not always handle gamma correction
correctly when combined with alpha transparency.

------

INTRODUCTION

The PNG-to-DIB function creates version 3.0 DIBs/BMPs. The image will be
uncompressed, with either 1, 4, 8, or 24 bits-per-pixel.

(Note: A BMP image file is basically just a DIB copied directly from
memory, with a 14-byte file header tacked onto the front. The terms DIB
and BMP may sometimes be used almost interchangeably.)


The DIB-to-PNG function supports approximately version 3.0 DIBs, and also
OS/2-style DIBs. It supports bit depths of 1, 4, 8, 16, 24, and 32
bits-per-pixel. It supports 4 bpp and 8 bpp compressed DIBs (it uses
Windows GDI functions to uncompress them).

If you find a valid BMP file that the bmp2png sample program can't read,
please let me know.


Two sample programs, png2bmp.c and bmp2png.c, are included which demonstrate
the use of library functions. They can be compiled as "console mode" Win32
applications.

A third sample, "smview", is a bare-bones Windows program that uses pngdib
to read and display PNG files. This is intended to demonstrate that it is
easy to add PNG support to an application that uses DIBs. It is not
intended to be a usable image viewer.

--------

BRIEF INSTRUCTIONS FOR THE SAMPLE PNG VIEWER (smview)

[This program is just a demo. For a more usable viewer, visit
http://pobox.com/~jason1/purpleview/.]

Load a PNG image by selecting File|Open from the menu, or by drag-and-drop
from Windows Explorer.

Gamma Correction - Toggles gamma correction. If you turn this off, some
images, or parts of images, will look too light or too dark.

Save As PNG - Saves the visible (unstretched) image to a file.
IMPORTANT--- This saves the image as it is currently being displayed. The
saved image will not have any transparency, and the background color and
gamma correction will be applied to the image, not saved as meta-data.
This means that you can lose information by loading and then saving a PNG
image.

Background colors - You can define a background color that will be used in
certain situations. The following logic is used to select a background
color: If "Use Image's Background Color" is checked, and the current PNG
image file contains a suggested background color, that suggested
background color will be used. Otherwise, if "Use Custom Background Color"
is checked, your custom background color will be used (by default this is
a very light gray color). Otherwise, no background color will be used at
all, and transparency information in the image will be completely ignored.
Some images will not look very good in this situation. (A pure white
background will be used for the window, but will not be applied to the
image.)

Any time you make a change to the gamma or background color settings, the
PNG file will be reloaded from disk. That's not the ideal thing to do, but
this _is_ just a demo program...

--------

Basic instructions for using the library in your own programs (the
read_png_to_dib and write_dib_to_png functions) follow the change log
and TO DO list.

CHANGES in PNGDIB v2.2.0 (vs. 2.1.1)
------------------------------------

* Option to use HeapAlloc instead of GlobalAlloc (when reading PNGs).


CHANGES in PNGDIB v2.1.1 (vs. 2.1.0)
------------------------------------

* More accurate conversion of 16-bpp DIBs into PNGs.

* Some minor changes (mostly typecasts) to the pngdib.c and smview.c
code to try to avoid compiler warnings and errors.


CHANGES in PNGDIB v2.1.0 (vs. 2.0.0)
------------------------------------

* Added some fields to return image information (original bit depth,
resolution, etc.) when reading PNG images.

* Added pngdib_get_version and pngdib_get_version_string functions.

* -Removed- some features from the sample viewer program. It was getting
too big to be a useful demo. The feature-ful version has been spun off
into a separate project.

* (v2.1.0 is backward-compatible with v2.0.0. I think.)


CHANGES in PNGDIB v2.0.0 (vs. 1.x)
----------------------------------

* WARNING: v2.0 is neither source- nor binary-compatible with v1.x.
Compatibility *could* have been done, but frankly I'm not too concerned
about it. You shouldn't be using this as a shared library anyway. And you
really ought to update your source to use the new transparency features.
:-)

* Optional transparency and background-color processing when reading PNG
images.

* Optional gamma correction when reading PNG images.

* PNG files that you write are now labeled with a gamma of 0.45455,
indicating that they are in the standard sRGB color space, which is
(reasonably close to) the color space used by nearly all Windows displays.
There's no option to change this value, but it can be turned off
completely.

* Error messages can now be retrieved by the caller.


TO DO
-----

* Improve this documentation.

* Use CreateFile() and related functions instead of fopen(), etc.

* Make the transparency processing code less complicated.

* Investigate the possibility of returning an alpha channel in the DIB or
elsewhere.


======================================================================

int read_png_to_dib(PNGD_P2DINFO *p2dp)

This function takes the filename of an existing PNG file, reads it and
converts it into an equivalent Windows Device Independent Bitmap (DIB).

USAGE

Create a structure of type PNGD_P2DINFO, zero all the fields, then set the
fields below as needed.

Field        Type        Value
------------ ----------- ------------------------------------------
.structsize  DWORD       Set this to sizeof(PNGD_P2DINFO)

.flags       DWORD       Combination of the following values (see below):
                           PNGD_USE_BKGD
                           PNGD_USE_CUSTOM_BG
                           PNGD_GAMMA_CORRECTION
						   PNGD_USE_HEAPALLOC

.pngfn       char*       Pointer to null-terminated filename of the PNG
                         file to read.

.bgcolor     PNGD_COLOR_struct
                         The background color to use when reading the
                         PNG image (if it includes transparency). You must
                         set the PNGD_USE_CUSTOM_BG flag for this to be used.
                         Note that PNGDIB may modify this field (if you
                         set PNGD_USE_BKGD).

.errmsg      char*       This should point to a buffer of at least 100
                         characters. If PNGDIB fails, an error message will
                         be written here. This field can be NULL if you don't
                         want error messages.

.heap        HANDLE      If you set the PNGD_USE_HEAPALLOC flag, PNGDIB will
                         use HeapAlloc instead of GlobalAlloc to allocate
						 memory for the DIB. In that case, you can provide
						 a handle to the heap to use. If you set this to
						 NULL, PNGDIB will use the default heap (from
						 GetProcessHeap).

RETURN VALUE

Returns 0 on success; returns a nonzero error code on error (see table at
end of this document). If there was an error, the values returned in the
PNGD_P2DINFO struct are undefined.

If successful, the function will set values for some of the fields in your
PNGD_P2DINFO structure:


FLAGS:

PNGD_USE_BKGD

If set, PNGDIB will use the PNG file's suggested background color, if it
has one.
If unset, PNGDIB will ignore any suggested background color in the PNG file.

PNGD_USE_CUSTOM_BG

If set, indicates that you are providing your own background color in the
bgcolor field. If you are intending only to display (rather than edit) the
image, it is recommended that you provide a custom background color
whenever possible -- otherwise some PNG images may look pretty bad. The
color you choose is up to you, and depends on your application. If you
have no idea, a gray color may be safer than pure black or white.

IMPORTANT: If you set both PNGD_USE_CUSTOM_BG and PNGD_USE_BKGD, the PNG
file's suggested background color will be used if it has one. Your custom
background color will be used if and only if PNG file does not have a
suggested background color.

PNGD_GAMMA_CORRECTION

If you set this flag, PNGDIB will perform gamma correction when it reads
PNG images. It assumes that the resulting DIB image will be in the sRGB
color space. Unlabeled PNG images are assumed to be in the sRGB color
space. If you do not set this flag, no gamma correction will be done. You
should usually turn on this flag, especially if you are intending only to
display (rather than edit) the image.

---

Fields returned or modified by read_png_to_dib:

Field        Type        Value
------------ ----------- ------------------------------------------
.flags       DWORD       The following bits may be set by the function:
                          PNGD_BG_RETURNED - set if the PNG image was
                              composited against a background color.
                              The color used is then returned in the
                              bgcolor field.
                          PNGD_RES_RETURNED - set if xres,yres,res_units
                              fields are valid
                          PNGD_GAMMA_RETURNED - set if file_gamma is valid

.lpdib       LPBITMAPINFOHEADER
                         A pointer to the start of the new DIB in memory.
                         This might more correctly be of type LPBITMAPINFO,
                         but that is less convenient most of the time. Cast
                         its type if necessary. This memory block will
                         contain the BITMAPINFOHEADER, followed by the
                         palette (if present), followed by the bitmap bits.
                         The library will allocate a fixed memory block
                         using GlobalAlloc (or HeapAlloc, if you used the
						 PNGD_USE_HEAPALLOC flag). It is your responsibility
						 to free it with GlobalFree (or HeapFree) when you're
						 done with it.

.dibsize     int         The size in bytes of the DIB in memory (pointed to
                         by lpdib).

.palette_offs  int       Integer offset (in bytes) of the palette from the
                         start of lpdib. This will generally be 40.

.bits_offs   int         Integer offset (in bytes) of the bitmap bits from
                         the start of lpdib. Calculating
                         bits_offset-palette_offset will give you the size
                         of the palette, in bytes.

.palette     RGBQUAD*    Direct pointer to the palette. Note that this
                         field is redundant and can be calculated from
                         lpdib and palette_offs.

.palette_colors  int     The number of colors in the palette. This is
                         generally the same as lpdib->biClrUsed.

.lpbits      void*       Direct pointer to the bitmap bits. Note that this
                         field is redundant and can be calculated from
                         lpdib and bits_offs.
                         This field was accidentally named ".bits" in
                         PNGDIB version 1.x.

.bgcolor     PNGD_COLOR_struct
                         If a background color was used when reading the
                         image, it will be returned here and the
                         PNGD_RETURNED_BG flag will be set.

.color_type       int    The color type (based on the PNG spec).
.bits_per_sample  int    Bits per color sample, or per palette entry.
.bits_per_pixel   int    Bits per pixel, or per palette entry.
.interlace        int    >0 if the image was interlaced.
.res_x,res_y      int    X and Y resolution
.res_units        int    1==resolution is in pixels per meter;
                         0==resolution units are unspecified
.file_gamma     double   File gamma (e.g. 0.50000)


EXAMPLE

See the included file png2bmp.c or smview.c for an example of this function
being used.


======================================================================

int write_dib_to_png(PNGD_D2PINFO *d2pp)

USAGE

Create a structure of type PNGD_D2PINFO, zero all the fields, then set the
fields below as needed.

Field        Type        Value
------------ ----------- ------------------------------------------
.structsize  DWORD       Set this to sizeof(PNGD_D2PINFO)

.flags       DWORD       Set to 0 or a combination of:
                           PNGD_INTERLACE - to write an interlaced PNG image
                           PNGD_NO_GAMMA_LABEL - to suppress writing a gamma
                             value to the file

.pngfn       char*       Pointer to null-terminated filename of the PNG file
                         to write.

.lpdib       LPBITMAPINFOHEADER
                         Set this to point to the start of start of your DIB
                         [header and palette] in memory.

.dibsize     int         The size in bytes of the data pointed to by lpdib.
                         This field is optional, and can be set to zero. If
                         you set it, it may allow better error checking.

.lpbits      void*       Pointer to the start of the bitmap bits in memory.
                         Most of the time, the bits data in a DIB
                         immediately follows the header and palette (if
                         present). If that is the case, you can just set
                         lpbits to NULL, and the library will find it.

.bitssize    int         The size in bytes of the data pointed to by lpbits.
                         This field is optional, and can be set to zero. If
                         you set it, it may allow better error checking.

.software    char*       Pointer to a brief NULL-terminated string
                         identifying your application. Set to NULL if you
                         don't want your app to be identified in the PNG
                         file.

.errmsg      char*       This should point to a buffer of at least 100
                         characters. If PNGDIB fails, an error message will
                         be written here. This field can be NULL if you don't
                         want error messages.

RETURN VALUE

Returns 0 on success; returns a nonzero error code on error (see table below).


EXAMPLE

See the included file bmp2png.c for an example of this function being used.


======================================================================

Table of error codes (from pngdib.h):


#define PNGD_E_SUCCESS   0
#define PNGD_E_ERROR     1   // unspecified error
#define PNGD_E_VERSION   2   // struct size problem
#define PNGD_E_NOMEM     3   // could not alloc memory
#define PNGD_E_UNSUPP    4   // unsupported image type
#define PNGD_E_LIBPNG    5   // libpng error (invalid PNG?)
#define PNGD_E_BADBMP    6   // corrupt or unsupported DIB
#define PNGD_E_BADPNG    7   // corrupt or unsupported PNG
#define PNGD_E_READ      8   // couldn't read PNG file
#define PNGD_E_WRITE     9   // couldn't write PNG file