From 61946e0f56ef01c7941f1e5776ad5ac7d7f73787 Mon Sep 17 00:00:00 2001 From: Glenn Randers-Pehrson Date: Sun, 28 Apr 2013 20:48:37 -0500 Subject: [PATCH] [libpng16] Revise man page to demonstrate dealing with unknown chunk handling in libpng.1.5.x and with bugs in libpng-1.4.x and earlier. --- libpng-manual.txt | 46 +++++++++++++++++++++++++++------------- libpng.3 | 54 ++++++++++++++++++++++++++++++----------------- 2 files changed, 66 insertions(+), 34 deletions(-) diff --git a/libpng-manual.txt b/libpng-manual.txt index 3adfb26e1..09f111d1d 100644 --- a/libpng-manual.txt +++ b/libpng-manual.txt @@ -1,6 +1,6 @@ libpng-manual.txt - A description on how to use and modify libpng - libpng version 1.6.3beta03 - April 27, 2013 + libpng version 1.6.3beta03 - April 29, 2013 Updated and distributed by Glenn Randers-Pehrson Copyright (c) 1998-2013 Glenn Randers-Pehrson @@ -11,7 +11,7 @@ libpng-manual.txt - A description on how to use and modify libpng Based on: - libpng versions 0.97, January 1998, through 1.6.3beta03 - April 27, 2013 + libpng versions 0.97, January 1998, through 1.6.3beta03 - April 29, 2013 Updated and distributed by Glenn Randers-Pehrson Copyright (c) 1998-2013 Glenn Randers-Pehrson @@ -3104,17 +3104,33 @@ Here is an example of writing two private chunks, prVt and miNE: #ifdef PNG_WRITE_UNKNOWN_CHUNKS_SUPPORTED /* Set unknown chunk data */ - png_unknown_chunk unkc[2]; - png_set_keep_unknown_chunks(png, PNG_HANDLE_CHUNK_ALWAYS, NULL, 0); - strcpy((char *) unkc[0].name, "prVt"; - unkc[0].data = (unsigned char *) "PRIVATE CHUNK DATA"; - unkc[0].size = strlen(unkc[0].data)+1; - unkc[0].location = PNG_HAVE_IHDR; - strcpy((char *) unkc[1].name, "miNE"; - unkc[1].data = (unsigned char *) "MY CHUNK DATA"; - unkc[1].size = strlen(unkc[0].data)+1; - unkc[1].location = PNG_AFTER_IDAT; - png_set_unknown_chunks(png, info, unkc, 2); + png_unknown_chunk unk_chunk[2]; + strcpy((char *) unk_chunk[0].name, "prVt"; + unk_chunk[0].data = (unsigned char *) "PRIVATE DATA"; + unk_chunk[0].size = strlen(unk_chunk[0].data)+1; + unk_chunk[0].location = PNG_HAVE_IHDR; + strcpy((char *) unk_chunk[1].name, "miNE"; + unk_chunk[1].data = (unsigned char *) "MY CHUNK DATA"; + unk_chunk[1].size = strlen(unk_chunk[0].data)+1; + unk_chunk[1].location = PNG_AFTER_IDAT; + png_set_unknown_chunks(write_ptr, write_info_ptr, + unk_chunk, 2); + /* Needed because miNE is not safe-to-copy */ + png_set_keep_unknown_chunks(png, PNG_HANDLE_CHUNK_ALWAYS, + (png_bytep) "miNE", 1); + # if PNG_LIBPNG_VER < 10600 + /* Deal with unknown chunk location bug in 1.5.x and earlier */ + png_set_unknown_chunk_location(png, info, 0, PNG_HAVE_IHDR); + png_set_unknown_chunk_location(png, info, 1, PNG_AFTER_IDAT); + # endif + # if PNG_LIBPNG_VER < 10500 + /* PNG_AFTER_IDAT writes two copies of the chunk prior to libpng-1.5.0, + * one before IDAT and another after IDAT, so don't use it; only use + * PNG_HAVE_IHDR location. This call resets the location previously + * set by assignment and png_set_unknown_chunk_location() for chunk 1. + */ + png_set_unknown_chunk_location(png, info, 1, PNG_HAVE_IHDR); + # endif #endif The high-level write interface @@ -4965,7 +4981,7 @@ We no longer include string.h in png.h. The include statement has been moved to pngpriv.h, where it is not accessible by applications. Applications that need access to information in string.h must add an '#include ' directive. It does not matter whether this is placed prior to or after -the '"#include png.h"' directive. +the '#include "png.h"' directive. The following API are now DEPRECATED: png_info_init_3() @@ -5181,7 +5197,7 @@ Other rules can be inferred by inspecting the libpng source. XVI. Y2K Compliance in libpng -April 27, 2013 +April 29, 2013 Since the PNG Development group is an ad-hoc body, we can't make an official declaration. diff --git a/libpng.3 b/libpng.3 index 597f9d0e2..d56b0b81c 100644 --- a/libpng.3 +++ b/libpng.3 @@ -1,4 +1,4 @@ -.TH LIBPNG 3 "April 27, 2013" +.TH LIBPNG 3 "April 29, 2013" .SH NAME libpng \- Portable Network Graphics (PNG) Reference Library 1.6.3beta03 .SH SYNOPSIS @@ -504,7 +504,7 @@ Following is a copy of the libpng-manual.txt file that accompanies libpng. .SH LIBPNG.TXT libpng-manual.txt - A description on how to use and modify libpng - libpng version 1.6.3beta03 - April 27, 2013 + libpng version 1.6.3beta03 - April 29, 2013 Updated and distributed by Glenn Randers-Pehrson Copyright (c) 1998-2013 Glenn Randers-Pehrson @@ -515,7 +515,7 @@ libpng-manual.txt - A description on how to use and modify libpng Based on: - libpng versions 0.97, January 1998, through 1.6.3beta03 - April 27, 2013 + libpng versions 0.97, January 1998, through 1.6.3beta03 - April 29, 2013 Updated and distributed by Glenn Randers-Pehrson Copyright (c) 1998-2013 Glenn Randers-Pehrson @@ -3608,17 +3608,33 @@ Here is an example of writing two private chunks, prVt and miNE: #ifdef PNG_WRITE_UNKNOWN_CHUNKS_SUPPORTED /* Set unknown chunk data */ - png_unknown_chunk unkc[2]; - png_set_keep_unknown_chunks(png, PNG_HANDLE_CHUNK_ALWAYS, NULL, 0); - strcpy((char *) unkc[0].name, "prVt"; - unkc[0].data = (unsigned char *) "PRIVATE CHUNK DATA"; - unkc[0].size = strlen(unkc[0].data)+1; - unkc[0].location = PNG_HAVE_IHDR; - strcpy((char *) unkc[1].name, "miNE"; - unkc[1].data = (unsigned char *) "MY CHUNK DATA"; - unkc[1].size = strlen(unkc[0].data)+1; - unkc[1].location = PNG_AFTER_IDAT; - png_set_unknown_chunks(png, info, unkc, 2); + png_unknown_chunk unk_chunk[2]; + strcpy((char *) unk_chunk[0].name, "prVt"; + unk_chunk[0].data = (unsigned char *) "PRIVATE DATA"; + unk_chunk[0].size = strlen(unk_chunk[0].data)+1; + unk_chunk[0].location = PNG_HAVE_IHDR; + strcpy((char *) unk_chunk[1].name, "miNE"; + unk_chunk[1].data = (unsigned char *) "MY CHUNK DATA"; + unk_chunk[1].size = strlen(unk_chunk[0].data)+1; + unk_chunk[1].location = PNG_AFTER_IDAT; + png_set_unknown_chunks(write_ptr, write_info_ptr, + unk_chunk, 2); + /* Needed because miNE is not safe-to-copy */ + png_set_keep_unknown_chunks(png, PNG_HANDLE_CHUNK_ALWAYS, + (png_bytep) "miNE", 1); + # if PNG_LIBPNG_VER < 10600 + /* Deal with unknown chunk location bug in 1.5.x and earlier */ + png_set_unknown_chunk_location(png, info, 0, PNG_HAVE_IHDR); + png_set_unknown_chunk_location(png, info, 1, PNG_AFTER_IDAT); + # endif + # if PNG_LIBPNG_VER < 10500 + /* PNG_AFTER_IDAT writes two copies of the chunk prior to libpng-1.5.0, + * one before IDAT and another after IDAT, so don't use it; only use + * PNG_HAVE_IHDR location. This call resets the location previously + * set by assignment and png_set_unknown_chunk_location() for chunk 1. + */ + png_set_unknown_chunk_location(png, info, 1, PNG_HAVE_IHDR); + # endif #endif .SS The high-level write interface @@ -5470,7 +5486,7 @@ We no longer include string.h in png.h. The include statement has been moved to pngpriv.h, where it is not accessible by applications. Applications that need access to information in string.h must add an '#include ' directive. It does not matter whether this is placed prior to or after -the '"#include png.h"' directive. +the '#include "png.h"' directive. The following API are now DEPRECATED: png_info_init_3() @@ -5686,7 +5702,7 @@ Other rules can be inferred by inspecting the libpng source. .SH XVI. Y2K Compliance in libpng -April 27, 2013 +April 29, 2013 Since the PNG Development group is an ad-hoc body, we can't make an official declaration. @@ -5963,7 +5979,7 @@ possible without all of you. Thanks to Frank J. T. Wojcik for helping with the documentation. -Libpng version 1.6.3beta03 - April 27, 2013: +Libpng version 1.6.3beta03 - April 29, 2013: Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc. Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net). @@ -5986,7 +6002,7 @@ this sentence. This code is released under the libpng license. -libpng versions 1.2.6, August 15, 2004, through 1.6.3beta03, April 27, 2013, are +libpng versions 1.2.6, August 15, 2004, through 1.6.3beta03, April 29, 2013, are Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are distributed according to the same disclaimer and license as libpng-1.2.5 with the following individual added to the list of Contributing Authors @@ -6085,7 +6101,7 @@ certification mark of the Open Source Initiative. Glenn Randers-Pehrson glennrp at users.sourceforge.net -April 27, 2013 +April 29, 2013 .\" end of man page