From 49f9c249108a870dbaef654ed58cfdf1af1efcaf Mon Sep 17 00:00:00 2001 From: Glenn Randers-Pehrson Date: Sat, 27 Apr 2013 18:03:03 -0500 Subject: [PATCH] [libpng16] Expanded manual paragraph about writing private chunks, particularly about the need to call png_set_keep_unknown_chunks() when writing them. --- ANNOUNCE | 6 ++++-- CHANGES | 4 +++- libpng-manual.txt | 44 ++++++++++++++++++++++++++------------- libpng.3 | 52 +++++++++++++++++++++++++++++++---------------- 4 files changed, 71 insertions(+), 35 deletions(-) diff --git a/ANNOUNCE b/ANNOUNCE index 27770de03..904f34f96 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 @@ Version 1.6.3beta02 [April 26, 2013] 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 536cf7e1f..71ccd7637 100644 --- a/CHANGES +++ b/CHANGES @@ -4517,7 +4517,9 @@ Version 1.6.3beta02 [April 26, 2013] 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 41a7ce3d6..3adfb26e1 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 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 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 @@ 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 -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 @@ a writeable buffer of at least 29 bytes. 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 @@ 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 ' directive. It does not matter whether this is placed prior to or after the '"#include png.h"' directive. @@ -5165,7 +5181,7 @@ Other rules can be inferred by inspecting the libpng source. 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 e2d48ed36..597f9d0e2 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 @@ 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 26, 2013 + libpng version 1.6.3beta03 - April 27, 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 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 @@ 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 -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 @@ 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 -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 @@ 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 ' directive. It does not matter whether this is placed prior to or after the '"#include png.h"' directive. @@ -5670,7 +5686,7 @@ Other rules can be inferred by inspecting the libpng source. .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 @@ possible without all of you. 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 sentence. 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 @@ certification mark of the Open Source Initiative. Glenn Randers-Pehrson glennrp at users.sourceforge.net -April 26, 2013 +April 27, 2013 .\" end of man page