[libpng16] Expanded manual paragraph about writing private chunks, particularly
about the need to call png_set_keep_unknown_chunks() when writing them.
diff --git a/ANNOUNCE b/ANNOUNCE
index 27770de..904f34f 100644
--- a/ANNOUNCE
+++ b/ANNOUNCE
@@ -1,5 +1,5 @@
-Libpng 1.6.3beta03 - April 26, 2013
+Libpng 1.6.3beta03 - April 27, 2013
This is not intended to be a public release. It will be replaced
within a few weeks by a public version or by another test version.
@@ -35,7 +35,9 @@
Test for 'arm*' not just 'arm' in the host_cpu configure variable.
Rebuilt the configure scripts.
-Version 1.6.3beta03 [April 26, 2013]
+Version 1.6.3beta03 [April 27, 2013]
+ Expanded manual paragraph about writing private chunks, particularly
+ the need to call png_set_keep_unknown_chunks() when writing them.
Send comments/corrections/commendations to png-mng-implement at lists.sf.net
(subscription required; visit
diff --git a/CHANGES b/CHANGES
index 536cf7e..71ccd76 100644
--- a/CHANGES
+++ b/CHANGES
@@ -4517,7 +4517,9 @@
Test for 'arm*' not just 'arm' in the host_cpu configure variable.
Rebuilt the configure scripts.
-Version 1.6.3beta03 [April 26, 2013]
+Version 1.6.3beta03 [April 27, 2013]
+ Expanded manual paragraph about writing private chunks, particularly
+ the need to call png_set_keep_unknown_chunks() when writing them.
Send comments/corrections/commendations to png-mng-implement at lists.sf.net
(subscription required; visit
diff --git a/libpng-manual.txt b/libpng-manual.txt
index 41a7ce3..3adfb26 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 26, 2013
+ libpng version 1.6.3beta03 - April 27, 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.6.3beta03 - April 26, 2013
+ libpng versions 0.97, January 1998, through 1.6.3beta03 - April 27, 2013
Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2013 Glenn Randers-Pehrson
@@ -50,9 +50,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
@@ -3093,13 +3091,31 @@
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 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);
+ #endif
The high-level write interface
@@ -4947,7 +4963,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 "string.h"'
+need access to information in string.h must add an '#include <string.h>'
directive. It does not matter whether this is placed prior to or after
the '"#include png.h"' directive.
@@ -5165,7 +5181,7 @@
XVI. Y2K Compliance in libpng
-April 26, 2013
+April 27, 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 e2d48ed..597f9d0 100644
--- a/libpng.3
+++ b/libpng.3
@@ -1,4 +1,4 @@
-.TH LIBPNG 3 "April 26, 2013"
+.TH LIBPNG 3 "April 27, 2013"
.SH NAME
libpng \- Portable Network Graphics (PNG) Reference Library 1.6.3beta03
.SH SYNOPSIS
@@ -504,7 +504,7 @@
.SH LIBPNG.TXT
libpng-manual.txt - A description on how to use and modify libpng
- libpng version 1.6.3beta03 - April 26, 2013
+ libpng version 1.6.3beta03 - April 27, 2013
Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net>
Copyright (c) 1998-2013 Glenn Randers-Pehrson
@@ -515,7 +515,7 @@
Based on:
- libpng versions 0.97, January 1998, through 1.6.3beta03 - April 26, 2013
+ libpng versions 0.97, January 1998, through 1.6.3beta03 - April 27, 2013
Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2013 Glenn Randers-Pehrson
@@ -554,9 +554,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
@@ -3597,13 +3595,31 @@
.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 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);
+ #endif
.SS The high-level write interface
@@ -5452,7 +5468,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 "string.h"'
+need access to information in string.h must add an '#include <string.h>'
directive. It does not matter whether this is placed prior to or after
the '"#include png.h"' directive.
@@ -5670,7 +5686,7 @@
.SH XVI. Y2K Compliance in libpng
-April 26, 2013
+April 27, 2013
Since the PNG Development group is an ad-hoc body, we can't make
an official declaration.
@@ -5947,7 +5963,7 @@
Thanks to Frank J. T. Wojcik for helping with the documentation.
-Libpng version 1.6.3beta03 - April 26, 2013:
+Libpng version 1.6.3beta03 - April 27, 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).
@@ -5970,7 +5986,7 @@
This code is released under the libpng license.
-libpng versions 1.2.6, August 15, 2004, through 1.6.3beta03, April 26, 2013, are
+libpng versions 1.2.6, August 15, 2004, through 1.6.3beta03, April 27, 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
@@ -6069,7 +6085,7 @@
Glenn Randers-Pehrson
glennrp at users.sourceforge.net
-April 26, 2013
+April 27, 2013
.\" end of man page
