[libpng15] Added demo of how to deal with unknown chunk location
to the man page.
diff --git a/libpng-manual.txt b/libpng-manual.txt
index 95321f8..c672b5b 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.5.16beta04 - April 26, 2013
+ libpng version 1.5.16beta04 - April 29, 2013
Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net>
Copyright (c) 1998-2013 Glenn Randers-Pehrson
@@ -11,7 +11,7 @@
Based on:
- libpng versions 0.97, January 1998, through 1.5.16beta04 - April 26, 2013
+ libpng versions 0.97, January 1998, through 1.5.16beta04 - April 29, 2013
Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2013 Glenn Randers-Pehrson
@@ -31,9 +31,7 @@
I. Introduction
This file describes how to use and modify the PNG reference library
-(known as libpng) for your own use. There are five sections to this
-file: introduction, structures, reading, writing, and modification and
-configuration notes for various special platforms. In addition to this
+(known as libpng) for your own use. In addition to this
file, example.c is a good starting point for using the library, as
it is heavily commented and should include everything most people
will need. We assume that libpng is already installed; see the
@@ -3037,13 +3035,45 @@
Writing unknown chunks
-You can use the png_set_unknown_chunks function to queue up chunks
-for writing. You give it a chunk name, raw data, and a size; that's
-all there is to it. The chunks will be written by the next following
-png_write_info_before_PLTE, png_write_info, or png_write_end function.
-Any chunks previously read into the info structure's unknown-chunk
-list will also be written out in a sequence that satisfies the PNG
-specification's ordering rules.
+You can use the png_set_unknown_chunks function to queue up private chunks
+for writing. You give it a chunk name, location, raw data, and a size. You
+also must use png_set_keep_unknown_chunks() to ensure that libpng will
+handle them. That's all there is to it. The chunks will be written by the
+next following png_write_info_before_PLTE, png_write_info, or png_write_end
+function, depending upon the specified location. Any chunks previously
+read into the info structure's unknown-chunk list will also be written out
+in a sequence that satisfies the PNG specification's ordering rules.
+
+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 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);
+ /* 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);
+ # 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
@@ -4625,7 +4655,7 @@
XIV. Y2K Compliance in libpng
-April 26, 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 91d47be..edec271 100644
--- a/libpng.3
+++ b/libpng.3
@@ -1,4 +1,4 @@
-.TH LIBPNG 3 "April 26, 2013"
+.TH LIBPNG 3 "April 29, 2013"
.SH NAME
libpng \- Portable Network Graphics (PNG) Reference Library 1.5.16beta04
.SH SYNOPSIS
@@ -492,7 +492,7 @@
.SH LIBPNG.TXT
Libpng-manual.txt - A description on how to use and modify libpng
- libpng version 1.5.16beta04 - April 26, 2013
+ libpng version 1.5.16beta04 - April 29, 2013
Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net>
Copyright (c) 1998-2013 Glenn Randers-Pehrson
@@ -503,7 +503,7 @@
Based on:
- libpng versions 0.97, January 1998, through 1.5.16beta04 - April 26, 2013
+ libpng versions 0.97, January 1998, through 1.5.16beta04 - April 29, 2013
Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2013 Glenn Randers-Pehrson
@@ -523,9 +523,7 @@
.SH I. Introduction
This file describes how to use and modify the PNG reference library
-(known as libpng) for your own use. There are five sections to this
-file: introduction, structures, reading, writing, and modification and
-configuration notes for various special platforms. In addition to this
+(known as libpng) for your own use. In addition to this
file, example.c is a good starting point for using the library, as
it is heavily commented and should include everything most people
will need. We assume that libpng is already installed; see the
@@ -3529,13 +3527,45 @@
.SS Writing unknown chunks
-You can use the png_set_unknown_chunks function to queue up chunks
-for writing. You give it a chunk name, raw data, and a size; that's
-all there is to it. The chunks will be written by the next following
-png_write_info_before_PLTE, png_write_info, or png_write_end function.
-Any chunks previously read into the info structure's unknown-chunk
-list will also be written out in a sequence that satisfies the PNG
-specification's ordering rules.
+You can use the png_set_unknown_chunks function to queue up private chunks
+for writing. You give it a chunk name, location, raw data, and a size. You
+also must use png_set_keep_unknown_chunks() to ensure that libpng will
+handle them. That's all there is to it. The chunks will be written by the
+next following png_write_info_before_PLTE, png_write_info, or png_write_end
+function, depending upon the specified location. Any chunks previously
+read into the info structure's unknown-chunk list will also be written out
+in a sequence that satisfies the PNG specification's ordering rules.
+
+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 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);
+ /* 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);
+ # 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
@@ -5118,7 +5148,7 @@
.SH XIV. Y2K Compliance in libpng
-April 26, 2013
+April 29, 2013
Since the PNG Development group is an ad-hoc body, we can't make
an official declaration.
@@ -5407,7 +5437,7 @@
Thanks to Frank J. T. Wojcik for helping with the documentation.
-Libpng version 1.5.16beta04 - April 26, 2013:
+Libpng version 1.5.16beta04 - 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).
@@ -5430,7 +5460,7 @@
This code is released under the libpng license.
-libpng versions 1.2.6, August 15, 2004, through 1.5.16beta04, April 26, 2013, are
+libpng versions 1.2.6, August 15, 2004, through 1.5.16beta04, 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
@@ -5529,7 +5559,7 @@
Glenn Randers-Pehrson
glennrp at users.sourceforge.net
-April 26, 2013
+April 29, 2013
.\" end of man page
