[libpng17] Expanded manual paragraph about writing private chunks.

ANNOUNCE

@@ -1,5 +1,5 @@
 
-Libpng 1.7.0beta12 - April 26, 2013
+Libpng 1.7.0beta12 - April 29, 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.
@@ -268,7 +268,10 @@ Version 1.7.0beta10 [April 24, 2013]
 Version 1.7.0beta11 [April 26, 2013]
   Test for 'arm*', not just 'arm' in the host_cpu configure variable.
 
-Version 1.7.0beta12 [April 26, 2013]
+Version 1.7.0beta12 [April 29, 2013]
+  Added png_app_warning for out-of-range unknown chunk index in
+    png_set_unknown_chunk_location().
+  Expanded manual paragraph about writing private chunks.
 
 Send comments/corrections/commendations to png-mng-implement at lists.sf.net
 (subscription required; visit

CHANGES

@@ -4556,7 +4556,10 @@ Version 1.7.0beta10 [April 24, 2013]
 Version 1.7.0beta11 [April 26, 2013]
   Test for 'arm*', not just 'arm' in the host_cpu configure variable.
 
-Version 1.7.0beta12 [April 26, 2013]
+Version 1.7.0beta12 [April 29, 2013]
+  Added png_app_warning for out-of-range unknown chunk index in
+    png_set_unknown_chunk_location().
+  Expanded manual paragraph about writing private chunks.
 
 Send comments/corrections/commendations to png-mng-implement at lists.sf.net
 (subscription required; visit

libpng-manual.txt

@@ -1,6 +1,6 @@
 libpng-manual.txt - A description on how to use and modify libpng
 
- libpng version 1.7.0beta12 - April 26, 2013
+ libpng version 1.7.0beta12 - 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 @@ libpng-manual.txt - A description on how to use and modify libpng
 
  Based on:
 
- libpng versions 0.97, January 1998, through 1.7.0beta12 - April 26, 2013
+ libpng versions 0.97, January 1998, through 1.7.0beta12 - April 29, 2013
  Updated and distributed by Glenn Randers-Pehrson
  Copyright (c) 1998-2013 Glenn Randers-Pehrson
 
@@ -51,9 +51,7 @@ libpng-manual.txt - A description on how to use and modify libpng
 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
+(known as libpng) for your own use.  In addition to this
-file: introduction, structures, reading, writing, and modification and
-configuration notes for various special platforms.  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
@@ -3092,13 +3090,34 @@ a writeable buffer of at least 29 bytes.
 
 Writing unknown chunks
 
-You can use the png_set_unknown_chunks function to queue up chunks
+You can use the png_set_unknown_chunks function to queue up private chunks
-for writing.  You give it a chunk name, raw data, and a size; that's
+for writing.  You give it a chunk name, location, raw data, and a size.  You
-all there is to it.  The chunks will be written by the next following
+also must use png_set_keep_unknown_chunks() to ensure that libpng will
-png_write_info_before_PLTE, png_write_info, or png_write_end function.
+handle them.  That's all there is to it.  The chunks will be written by the
-Any chunks previously read into the info structure's unknown-chunk
+next following png_write_info_before_PLTE, png_write_info, or png_write_end
-list will also be written out in a sequence that satisfies the PNG
+function, depending upon the specified location.  Any chunks previously
-specification's ordering rules.
+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);
+    #endif
 
 The high-level write interface
 
@@ -4946,9 +4965,9 @@ symbols, using the PNG_PREFIX macro.
 
 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.
+the '#include "png.h"' directive.
 
 The following API are now DEPRECATED:
    png_info_init_3()
@@ -5196,7 +5215,7 @@ Other rules can be inferred by inspecting the libpng source.
 
 XVII. 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.

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.7.0beta12
 .SH SYNOPSIS
@@ -494,7 +494,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.7.0beta12 - April 26, 2013
+ libpng version 1.7.0beta12 - April 29, 2013
  Updated and distributed by Glenn Randers-Pehrson
  <glennrp at users.sourceforge.net>
  Copyright (c) 1998-2013 Glenn Randers-Pehrson
@@ -505,7 +505,7 @@ libpng-manual.txt - A description on how to use and modify libpng
 
  Based on:
 
- libpng versions 0.97, January 1998, through 1.7.0beta12 - April 26, 2013
+ libpng versions 0.97, January 1998, through 1.7.0beta12 - April 29, 2013
  Updated and distributed by Glenn Randers-Pehrson
  Copyright (c) 1998-2013 Glenn Randers-Pehrson
 
@@ -545,9 +545,7 @@ libpng-manual.txt - A description on how to use and modify libpng
 .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
+(known as libpng) for your own use.  In addition to this
-file: introduction, structures, reading, writing, and modification and
-configuration notes for various special platforms.  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
@@ -3586,13 +3584,34 @@ a writeable buffer of at least 29 bytes.
 
 .SS Writing unknown chunks
 
-You can use the png_set_unknown_chunks function to queue up chunks
+You can use the png_set_unknown_chunks function to queue up private chunks
-for writing.  You give it a chunk name, raw data, and a size; that's
+for writing.  You give it a chunk name, location, raw data, and a size.  You
-all there is to it.  The chunks will be written by the next following
+also must use png_set_keep_unknown_chunks() to ensure that libpng will
-png_write_info_before_PLTE, png_write_info, or png_write_end function.
+handle them.  That's all there is to it.  The chunks will be written by the
-Any chunks previously read into the info structure's unknown-chunk
+next following png_write_info_before_PLTE, png_write_info, or png_write_end
-list will also be written out in a sequence that satisfies the PNG
+function, depending upon the specified location.  Any chunks previously
-specification's ordering rules.
+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);
+    #endif
 
 .SS The high-level write interface
 
@@ -5441,9 +5460,9 @@ symbols, using the PNG_PREFIX macro.
 
 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.
+the '#include "png.h"' directive.
 
 The following API are now DEPRECATED:
    png_info_init_3()
@@ -5691,7 +5710,7 @@ Other rules can be inferred by inspecting the libpng source.
 
 .SH XVII. 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.
@@ -5961,7 +5980,7 @@ possible without all of you.
 
 Thanks to Frank J. T. Wojcik for helping with the documentation.
 
-Libpng version 1.7.0beta12 - April 26, 2013:
+Libpng version 1.7.0beta12 - 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).
 
@@ -5984,7 +6003,7 @@ this sentence.
 
 This code is released under the libpng license.
 
-libpng versions 1.2.6, August 15, 2004, through 1.7.0beta12, April 26, 2013, are
+libpng versions 1.2.6, August 15, 2004, through 1.7.0beta12, 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
@@ -6083,7 +6102,7 @@ certification mark of the Open Source Initiative.
 
 Glenn Randers-Pehrson
 glennrp at users.sourceforge.net
-April 26, 2013
+April 29, 2013
 
 .\" end of man page