Chapter 15. Writing PNG Images

15.1. A libpng-Based, PNG-Writing Demo Program

15.2. Gamma Correction

15.3. Text Chunks

The specification also recommends that lines in each text block be no more than 79 characters long; I've chosen to restrict mine to 72 characters each, plus provide for one or two newline characters and a trailing NULL. The spec does not specifically address the issue of the final newline, but does require omitting the trailing NULL; logically, one might extend that to include trailing newlines, so I have.

    do {
        valid = TRUE;
        p = textbuf + TEXT_TITLE_OFFSET;
        fprintf(stderr, "  Title: ");
        fflush(stderr);
        if (FGETS(p, 74, keybd) && (len = strlen(p)) > 1) {
            if (p[len-1] == '\n')
                p[--len] = '\0';    /* remove trailing newline */
            wpng_info.title = p;
            wpng_info.have_text |= TEXT_TITLE;
  
            if ((result = wpng_isvalid_latin1((uch *)p, len)) >= 0) {
                fprintf(stderr, "    " PROGNAME " warning:  character"
                  " code %u is %sdiscouraged by the PNG\n"
                  "    specification [first occurrence was at
                  " character position #%d]\n", (unsigned)p[result],
                  (p[result] == 27)? "strongly " : "", result+1);
                fflush(stderr);
#ifdef FORBID_LATIN1_CTRL
                wpng_info.have_text &= ~TEXT_TITLE;
                valid = FALSE;
#else
                if (p[result] == 27) {      /* escape character */
                    wpng_info.have_text &= ~TEXT_TITLE;
                    valid = FALSE;
                }
#endif
            }
        }
    } while (!valid);

static int wpng_isvalid_latin1(uch *p, int len)
{
    int i, result = -1;
  
    for (i = 0;  i < len;  ++i) {
        if (p[i] == 10 || (p[i] > 31 && p[i] < 127) || p[i] > 160)
            continue;
        if (result < 0 || (p[result] != 27 && p[i] == 27))
            result = i;
    }
  
    return result;
}

Enter text info (no more than 72 characters per line);
to skip a field, hit the <Enter> key.
  Title: L'Arc de Triomphe
  Author: Greg Roelofs
  Description (up to 9 lines):
    [1] This line contains only normal characters.
    [2] This line contains a tab character here: ^I
    [3] 
    wpng warning:  character code 9 is discouraged by the PNG
    specification [first occurrence was at character position #85]
  Copyright: We attempt an escape character here: ^[
    wpng warning:  character code 27 is strongly discouraged by the PNG
    specification [first occurrence was at character position #38]
  Copyright: Copyright 1981, 1999 Greg Roelofs
  E-mail: roelofs@pobox.com
  URL: http://www.libpng.org/pub/png/pngbook.html

Note that the Copyright keyword had to be entered twice since the first attempt included an escape character. The Description keyword also would have had to be reentered if the program had been compiled with FORBID_LATIN1_CTRL defined.

typedef struct _mainprog_info {
    double gamma;
    long width;
    long height;
    time_t modtime;
    FILE *infile;
    FILE *outfile;
    void *png_ptr;
    void *info_ptr;
    uch *image_data;
    uch **row_pointers;
    char *title;
    char *author;
    char *desc;
    char *copyright;
    char *email;
    char *url;
    int filter;
    int pnmtype;
    int sample_depth;
    int interlaced;
    int have_bg;
    int have_time;
    int have_text;
    jmp_buf jmpbuf;
    uch bg_red;
    uch bg_green;
    uch bg_blue;
} mainprog_info;

As in the previous programs, we use the abbreviated typedefs uch, ush, and ulg in place of the more unwieldy unsigned char, unsigned short, and unsigned long, respectively. The title element is simply a pointer into the text buffer, and the struct contains similar pointers for the other five keywords. have_text is more than a simple Boolean (TRUE/FALSE) value, however. Because the user may not want all six text chunks, the program must keep track of which ones were provided with valid data. Thus, have_text is a bit flag, and TEXT_TITLE sets the bit corresponding to the Title keyword--but only if the length of the entered string is greater than one.

15.4. writepng_version_info()

#include "png.h"       /* libpng header; includes zlib.h */
#include "writepng.h"  /* typedefs, common macros, public prototypes */
  
void writepng_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);
}

writepng_version_info() simply indicates the versions of libpng and zlib with which the application was compiled, as well as the versions it happens to be using at runtime. Ideally the two pairs of version numbers will match--in the case of a statically linked executable, they always will--but if the program was dynamically linked, it is possible that the program loader has found either an older or a newer version of one or both libraries, in which case strange problems may arise later. Making this information easily available to the user, whether in a simple text-mode usage screen as I do here or via a windowed ``about box'' or even a fancy, automated, troubleshooting function, can be helpful in dealing with the bug reports that inevitably show up sooner or later.

15.5. writepng_init()

    if (user_specified_time_option) {
        wpng_info.modtime = time(NULL);
        wpng_info.have_time = TRUE;
    }

After finishing the command-line options, we next open the input file (in binary mode!), verify that it's in the proper format, and read its basic parameters: image height, width, and depth. We also generate an output filename based on the input name and verify both that the output file does not already exist and that it can be opened and written to (also in binary mode!). That provides enough information to fill in most of the rest of mainprog_info: infile, pnmtype, have_bg, width, height, sample_depth, and outfile.

If any errors have occurred by this point, wpng prints the usage screen--including the libraries' version information--and exits. Otherwise it optionally prompts the user for PNG text information and then, finally, calls our PNG initialization routine, writepng_init(). It is declared as follows:

int writepng_init(mainprog_info *mainprog_ptr)

where mainprog_ptr just points at the mainprog_info struct we filled in in the main program. writepng_init() begins with some fairly standard libpng boilerplate:

    png_structp  png_ptr;
    png_infop  info_ptr;
  
    png_ptr = png_create_write_struct(PNG_LIBPNG_VER_STRING,
      mainprog_ptr, writepng_error_handler, NULL);
    if (!png_ptr)
        return 4;   /* out of memory */
  
    info_ptr = png_create_info_struct(png_ptr);
    if (!info_ptr) {
        png_destroy_write_struct(&png_ptr, NULL);
        return 4;
    }

The second and third arguments to png_create_write_struct() are the keys to installing a custom error handler. The second argument is a pointer to application data (mainprog_ptr, in this case) that will be supplied to the error handler; the third argument is the custom error-handling routine itself. I will explain why it is important to use a custom routine as soon as we take a look at the next section of code.

    if (setjmp(mainprog_ptr->jmpbuf)) {
        png_destroy_write_struct(&png_ptr, &info_ptr);
        return 2;
    }

    png_init_io(png_ptr, mainprog_ptr->outfile);

    png_set_compression_level(png_ptr, Z_BEST_COMPRESSION);

Note that a good PNG-writing program should let the user decide whether and how to override the default settings; options for very fast saves and/or for maximal compression might be reasonable, in addition to the default. In fact, pnmtopng provides options to do just that.

Tweaking Compression Closely related to compression is filtering, one area in which it is almost always better to leave the decision up to libpng. Repeated tests have shown that filtering is almost never useful on palette-based images, but on everything else it is quite beneficial. Though libpng allows one to restrict its filter selection, this is rarely a good idea; dynamic filtering works best when the encoder can choose from the five defined filter types. But for programmers who want to play with the alternatives, here's an example: /* >>> this is pseudo-code if (palette image, i.e., don't want filtering) { png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE, PNG_FILTER_NONE); png_set_compression_strategy(png_ptr, Z_DEFAULT_STRATEGY); } else { >>> leave default filter selection alone png_set_compression_strategy(png_ptr, Z_FILTERED); } */ The calls to png_set_compression_strategy() actually alter zlib's behavior to work better with the filtered output. Other zlib parameters can also be tweaked, at least in theory; these include the sliding window size, memory level, and compression method. For the last, only method 8 is currently defined, but zlib 2.0 is likely to introduce at least one or two new methods when it is eventually released. Of course, unless and until the PNG specification is revised accordingly, no new compression method can be used within a PNG file without invalidating it. The window size is the only thing a normal PNG encoder should consider changing, and then only when the total size of the image data, plus one extra byte per row for the row filters, amounts to 16 kilobytes or less. In such a case, the encoder can use a smaller power-of-two window size without affecting compression, which allows decoders to reduce their memory usage. The following fragment shows how to modify these zlib parameters; the values shown are the defaults used by libpng (consult the libpng documentation, specifically ``Configuring zlib'' and ``Controlling row filtering''): /* >>> second arg is power of two; 8 through 15 (256-32768) valid png_set_compression_window_bits(png_ptr, 15); png_set_compression_mem_level(png_ptr, 8); png_set_compression_method(png_ptr, 8); */

    int color_type, interlace_type;
  
    if (mainprog_ptr->pnmtype == 5)
        color_type = PNG_COLOR_TYPE_GRAY;
    else if (mainprog_ptr->pnmtype == 6)
        color_type = PNG_COLOR_TYPE_RGB;
    else if (mainprog_ptr->pnmtype == 8)
        color_type = PNG_COLOR_TYPE_RGB_ALPHA;
    else {
        png_destroy_write_struct(&png_ptr, &info_ptr);
        return 11;
    }
  
    interlace_type = mainprog_ptr->interlaced? PNG_INTERLACE_ADAM7 :
                                               PNG_INTERLACE_NONE;

    png_set_IHDR(png_ptr, info_ptr, mainprog_ptr->width,
      mainprog_ptr->height, mainprog_ptr->sample_depth,
      color_type, interlace_type,
      PNG_COMPRESSION_TYPE_DEFAULT, PNG_FILTER_TYPE_DEFAULT);

    if (mainprog_ptr->gamma > 0.0)
        png_set_gAMA(png_ptr, info_ptr, mainprog_ptr->gamma);
  
    if (mainprog_ptr->have_bg) {
        png_color_16  background;
  
        background.red = mainprog_ptr->bg_red;
        background.green = mainprog_ptr->bg_green;
        background.blue = mainprog_ptr->bg_blue;
        png_set_bKGD(png_ptr, info_ptr, &background);
    }
  
    if (mainprog_ptr->have_time) {
        png_time  modtime;
  
        png_convert_from_time_t(&modtime, mainprog_ptr->modtime);
        png_set_tIME(png_ptr, info_ptr, &modtime);
    }

It is also worth noting that libpng copies most of the data it needs into its own structs, so we can get away with using temporary variables like background and modtime without worrying about their values being corrupted before libpng is ready to write them to the file. The only exceptions are things involving pointers, in which case libpng copies the pointer itself but not the buffer to which it points. In fact, libpng's text-handling code is an excellent example of that:

    if (mainprog_ptr->have_text) {
        png_text  text[6];
        int  num_text = 0;
  
        if (mainprog_ptr->have_text & TEXT_TITLE) {
            text[num_text].compression = PNG_TEXT_COMPRESSION_NONE;
            text[num_text].key = "Title";
            text[num_text].text = mainprog_ptr->title;
            ++num_text;
        }
        if (mainprog_ptr->have_text & TEXT_AUTHOR) {
            text[num_text].compression = PNG_TEXT_COMPRESSION_NONE;
            text[num_text].key = "Author";
            text[num_text].text = mainprog_ptr->author;
            ++num_text;
        }
        if (mainprog_ptr->have_text & TEXT_DESC) {
            text[num_text].compression = PNG_TEXT_COMPRESSION_NONE;
            text[num_text].key = "Description";
            text[num_text].text = mainprog_ptr->desc;
            ++num_text;
        }
        if (mainprog_ptr->have_text & TEXT_COPY) {
            text[num_text].compression = PNG_TEXT_COMPRESSION_NONE;
            text[num_text].key = "Copyright";
            text[num_text].text = mainprog_ptr->copyright;
            ++num_text;
        }
        if (mainprog_ptr->have_text & TEXT_EMAIL) {
            text[num_text].compression = PNG_TEXT_COMPRESSION_NONE;
            text[num_text].key = "E-mail";
            text[num_text].text = mainprog_ptr->email;
            ++num_text;
        }
        if (mainprog_ptr->have_text & TEXT_URL) {
            text[num_text].compression = PNG_TEXT_COMPRESSION_NONE;
            text[num_text].key = "URL";
            text[num_text].text = mainprog_ptr->url;
            ++num_text;
        }
        png_set_text(png_ptr, info_ptr, text, num_text);
    }

Text Buffers, PNG Structs, and Core Dumps The issue of libpng's allocation of its own text buffers is worth a closer look, because it indirectly led to a subtle but fatal bug in a popular PNG viewer. The program in question was John Bradley's XV, an elegant and powerful image viewer/converter for the X Window System. Version 3.10a, released late in 1994 and still the most recent release as of this writing, had no native PNG support. But because it was available in source-code form, it was one of the first applications to support the reading and writing of PNGs, thanks to a patch created by Alexander Lehmann in June 1995 and later modified by Andreas Dilger and the author of this book. This patch was originally written to work with libpng 0.71 and zlib 0.93, beta versions so old they were arguably alpha-level software. At the time, major functionality was still being added to libpng, and the so-called modern ``convenience functions'' for modifying libpng parameters did not exist. As a result, the patch was designed to access the two PNG structs directly, and later updates to the patch did not completely eliminate this behavior. In particular, all versions of the patch through 1.2d, released in June 1996, allocated their own text structs and plugged them directly into one of the main PNG structs for libpng's use. Now fast-forward to January 1998, when the final libpng betas were being released. By this time, libpng provided functions not only to allocate and destroy the PNG structs, but also to read from them and write to them. In particular, png_set_text() already existed in its present form; i.e., it allocated its own text structs and copied the user-supplied data into them. But one of the changes in libpng 0.97 involved plugging some small memory leaks by freeing these libpng-allocated text structs as part of png_destroy_write_struct(). Unfortunately, libpng had no way to track whether it had actually allocated the structs in the first place, and...well, one can see where this is going. First libpng freed the text structs, then the XV patch--which had allocated them--did so again. Boom: segmentation fault, core dump, an incomplete PNG file, and no more XV. The moral of this little story is simple: 1995-era programs had no choice but to access libpng structs directly, because that was how libpng was originally written. But modern programs should never do so, not only because of this particular problem, but also for the several other reasons detailed in the previous two chapters. Let's say it again: Accessing libpng structures directly is just plain evil. Don't do it! Ye have been warned.

    png_write_info(png_ptr, info_ptr);

Doing this flushes any time or text chunks to the output file, and the corresponding data in the PNG structs is marked so that it is not written to the file again later. I mentioned earlier that text buffers must remain valid until either png_write_info() or png_write_end() is called, which implies that either one can be used to write text chunks to the PNG file. This is indeed the case. Had we wished to put all of our text chunks (or the time chunk) at the end of the PNG file, we would have called png_write_info() first, followed by one or both of png_set_tIME() and png_set_text().

    png_set_packing(png_ptr);

This function packs low-bit-depth pixels into bytes. There are no low-bit-depth RGB and RGBA images; only grayscale and palette images support bit depths of 1, 2, or 4. But our main program neither counts colors to see whether a palette-based representation would be possible, nor checks for valid low-bit-depth grayscale values, and it always sets sample_depth to 8, so there is currently no possibility of libpng actually being able to pack any pixels. However, pnmtopng does both, and perhaps a subsequent revision of wpng will, too.

The only remaining thing for our initialization function to do is to save copies of the two PNG-struct pointers for passing to libpng functions later:

    mainprog_ptr->png_ptr = png_ptr;
    mainprog_ptr->info_ptr = info_ptr;
  
    return 0;

15.6. Interlaced PNG: writepng_encode_image()

What happens next depends on whether the user requested that the PNG image be interlaced. If so, there's really no good way to read and write the image progressively, so we simply allocate a buffer large enough for the whole thing and read it in. We also allocate and initialize a row_pointers array, where each element points at the beginning of a row of pixels, and then call writepng_encode_image():

int writepng_encode_image(mainprog_info *mainprog_ptr)
{
    png_structp png_ptr = (png_structp)mainprog_ptr->png_ptr;
    png_infop info_ptr = (png_infop)mainprog_ptr->info_ptr;
  
    if (setjmp(mainprog_ptr->jmpbuf)) {
        png_destroy_write_struct(&png_ptr, &info_ptr);
        mainprog_ptr->png_ptr = NULL;
        mainprog_ptr->info_ptr = NULL;
        return 2;
    }
  
    png_write_image(png_ptr, mainprog_ptr->row_pointers);
  
    png_write_end(png_ptr, NULL);
  
    return 0;
}

15.7. Noninterlaced PNG: writepng_encode_row()

int writepng_encode_row(mainprog_info *mainprog_ptr)
{
    png_structp png_ptr = (png_structp)mainprog_ptr->png_ptr;
    png_infop info_ptr = (png_infop)mainprog_ptr->info_ptr;
  
    if (setjmp(mainprog_ptr->jmpbuf)) {
        png_destroy_write_struct(&png_ptr, &info_ptr);
        mainprog_ptr->png_ptr = NULL;
        mainprog_ptr->info_ptr = NULL;
        return 2;
    }
  
    png_write_row(png_ptr, mainprog_ptr->image_data);
  
    return 0;
}

Astute readers will perceive that this function is almost identical to the previous one for interlaced images; the differences are the lack of a png_write_end() call (for obvious reasons) and the call to png_write_row() instead of png_write_image(). image_data now acts as our single row pointer.

Once the loop over rows completes, we call one last function to close out the PNG file:

int writepng_encode_finish(mainprog_info *mainprog_ptr)
{
    png_structp png_ptr = (png_structp)mainprog_ptr->png_ptr;
    png_infop info_ptr = (png_infop)mainprog_ptr->info_ptr;
  
    if (setjmp(mainprog_ptr->jmpbuf)) {
        png_destroy_write_struct(&png_ptr, &info_ptr);
        mainprog_ptr->png_ptr = NULL;
        mainprog_ptr->info_ptr = NULL;
        return 2;
    }

    png_write_end(png_ptr, NULL);
  
    return 0;
}

Again, the function is exactly like what we've seen before except that it calls png_write_end(). Alternatively, it could have been combined with writepng_encode_row() had we included in our mainprog_info struct a flag indicating whether the given row was the last one in the image.

15.8. writepng_cleanup()

void writepng_cleanup(mainprog_info *mainprog_ptr)
{
    png_structp png_ptr = (png_structp)mainprog_ptr->png_ptr;
    png_infop info_ptr = (png_infop)mainprog_ptr->info_ptr;
  
    if (png_ptr && info_ptr)
        png_destroy_write_struct(&png_ptr, &info_ptr);
}

15.9. Getting the Source Code