Preliminaries

Before we get into the heart of our basic demo program, I'll touch on a couple of mundane but nevertheless important details. The first is the libpng header file, png.h, which defines all of the libpng datatypes, declares all of the public function prototypes, and includes some useful macros. It must be included in any module that makes libpng function calls; in our case, we've segregated all of those in readpng.c, so that's the only place we need to include png.h:

#include "png.h"

Because png.h includes zlib.h, we need not include it explicitly, and most programs need not even worry about it, since there is rarely a need for the user's program to call zlib routines directly. But in our case we do want to make sure zlib.h is included somewhere. The reason for this is the second mundane detail: programs tend to be updated over time, and this often involves plugging in a newer version of a support library like libpng or zlib. When following up on a bug report, particularly with regard to software for which the source code is available (like the demo programs in this book), it is generally useful to know as much as possible about the version that exhibits the bug. In the presence of shared (dynamically linked) libraries, that's even more important. So as part of our demo program's usage screen--the poor man's version of an ``about box''--we call a very small routine in readpng.c that indicates not only the versions of libpng and zlib with which it was compiled, but also the versions it is currently using:

void readpng_version_info()
{
    fprintf(stderr, "   Compiled with libpng %s; using libpng %s.\n",
      PNG_LIBPNG_VER_STRING, png_libpng_ver);
    fprintf(stderr, "   Compiled with zlib %s; using zlib %s.\n",
      ZLIB_VERSION, zlib_version);
}

The uppercase values here are macros defined in the png.h and zlib.h header files; they indicate the compile-time versions. The lowercase variables are globals exported by the two libraries, so they give the versions actually in use at the time the program is run. Ideally, each pair of version numbers will match, but it is not unusual for the user, and sometimes even the programmer, to be caught by an unsuspected mismatch.