mewin/libpng
1
0
Fork 0
mirror of https://git.code.sf.net/p/libpng/code.git synced 2025-07-10 18:04:09 +02:00
Code Issues Projects Releases Wiki Activity

[libpng16] Better documentation of unknown handling API interactions.

Browse Source
This commit is contained in:
John Bowler
2013-03-02 17:59:43 -06:00
committed by Glenn Randers-Pehrson
parent e57f094fd6
commit e15b537825
5 changed files with 41 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
ANNOUNCE
View File

@@ -68,6 +68,7 @@ Version 1.6.1beta05 [March 1, 2013]
Avoid a possible memory leak in contrib/gregbook/readpng.c Avoid a possible memory leak in contrib/gregbook/readpng.c
Version 1.6.1beta06 [March 2, 2013] Version 1.6.1beta06 [March 2, 2013]
Better documentation of unknown handling API interactions.
Send comments/corrections/commendations to png-mng-implement at lists.sf.net Send comments/corrections/commendations to png-mng-implement at lists.sf.net
(subscription required; visit (subscription required; visit

1
CHANGES
View File

@@ -4425,6 +4425,7 @@ Version 1.6.1beta05 [March 1, 2013]
Avoid a possible memory leak in contrib/gregbook/readpng.c Avoid a possible memory leak in contrib/gregbook/readpng.c
Version 1.6.1beta06 [March 2, 2013] Version 1.6.1beta06 [March 2, 2013]
Better documentation of unknown handling API interactions.
Send comments/corrections/commendations to png-mng-implement at lists.sf.net Send comments/corrections/commendations to png-mng-implement at lists.sf.net
(subscription required; visit (subscription required; visit

17
libpng-manual.txt
View File

@@ -527,9 +527,14 @@ you can retrieve with
png_get_user_chunk_ptr(png_ptr); png_get_user_chunk_ptr(png_ptr);
If you call the png_set_read_user_chunk_fn() function, then all unknown If you call the png_set_read_user_chunk_fn() function, then all unknown
chunks will be saved when read, in case your callback function will need chunks which the callback does not handle will be saved when read. You can
one or more of them. This behavior can be changed with the cause them to be discarded by returning '1' ("handled") instead of '0'. This
png_set_keep_unknown_chunks() function, described below. behavior will change in libpng 1.7 and the default handling set by the
png_set_keep_unknown_chunks() function, described below, will be used when the
callback returns 0. If you want the existing behavior you should set the global
default to PNG_HANDLE_CHUNK_IF_SAFE now; this is compatible with all current
versions of libpng and with 1.7. Libpng 1.6 issues a warning if you keep the
default, or PNG_HANDLE_CHUNK_NEVER, and the callback returns 0.
At this point, you can set up a callback function that will be At this point, you can set up a callback function that will be
called after each row has been read, which you can use to control called after each row has been read, which you can use to control
@@ -628,8 +633,10 @@ callback function:
... ...
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED) #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
/* ignore all unknown chunks: */ /* ignore all unknown chunks
png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0); * (use global setting "2" for libpng16 and earlier):
*/
png_set_keep_unknown_chunks(read_ptr, 2, NULL, 0);
/* except for vpAg: */ /* except for vpAg: */
png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1); png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);

17
libpng.3
View File

@@ -1031,9 +1031,14 @@ you can retrieve with
png_get_user_chunk_ptr(png_ptr); png_get_user_chunk_ptr(png_ptr);
If you call the png_set_read_user_chunk_fn() function, then all unknown If you call the png_set_read_user_chunk_fn() function, then all unknown
chunks will be saved when read, in case your callback function will need chunks which the callback does not handle will be saved when read. You can
one or more of them. This behavior can be changed with the cause them to be discarded by returning '1' ("handled") instead of '0'. This
png_set_keep_unknown_chunks() function, described below. behavior will change in libpng 1.7 and the default handling set by the
png_set_keep_unknown_chunks() function, described below, will be used when the
callback returns 0. If you want the existing behavior you should set the global
default to PNG_HANDLE_CHUNK_IF_SAFE now; this is compatible with all current
versions of libpng and with 1.7. Libpng 1.6 issues a warning if you keep the
default, or PNG_HANDLE_CHUNK_NEVER, and the callback returns 0.
At this point, you can set up a callback function that will be At this point, you can set up a callback function that will be
called after each row has been read, which you can use to control called after each row has been read, which you can use to control
@@ -1132,8 +1137,10 @@ callback function:
... ...
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED) #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
/* ignore all unknown chunks: */ /* ignore all unknown chunks
png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0); * (use global setting "2" for libpng16 and earlier):
*/
png_set_keep_unknown_chunks(read_ptr, 2, NULL, 0);
/* except for vpAg: */ /* except for vpAg: */
png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1); png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);

21
png.h
View File

@@ -1838,7 +1838,7 @@ PNG_EXPORT(218, png_byte, png_get_current_pass_number, (png_const_structrp));
#endif #endif
#ifdef PNG_READ_USER_CHUNKS_SUPPORTED #ifdef PNG_READ_USER_CHUNKS_SUPPORTED
/* This callback is called only for *unknown* chunks, if /* This callback is called only for *unknown* chunks. If
* PNG_HANDLE_AS_UNKNOWN_SUPPORTED is set then it is possible to set known * PNG_HANDLE_AS_UNKNOWN_SUPPORTED is set then it is possible to set known
* chunks to be treated as unknown, however in this case the callback must do * chunks to be treated as unknown, however in this case the callback must do
* any processing required by the chunk (e.g. by calling the appropriate * any processing required by the chunk (e.g. by calling the appropriate
@@ -1850,12 +1850,12 @@ PNG_EXPORT(218, png_byte, png_get_current_pass_number, (png_const_structrp));
* The integer return from the callback function is interpreted thus: * The integer return from the callback function is interpreted thus:
* *
* negative: An error occured, png_chunk_error will be called. * negative: An error occured, png_chunk_error will be called.
* zero: The chunk was not handled, the chunk will be discarded unless * zero: The chunk was not handled, the chunk will be saved. A critical
* png_set_keep_unknown_chunks has been used to set a 'keep' behavior * chunk will cause an error at this point unless it is to be saved.
* for this particular chunk, in which case that will be used. A
* critical chunk will cause an error at this point unless it is to be
* saved.
* positive: The chunk was handled, libpng will ignore/discard it. * positive: The chunk was handled, libpng will ignore/discard it.
*
* See "INTERACTION WTIH USER CHUNK CALLBACKS" below for important notes about
* how this behavior will change in libpng 1.7
*/ */
PNG_EXPORT(88, void, png_set_read_user_chunk_fn, (png_structrp png_ptr, PNG_EXPORT(88, void, png_set_read_user_chunk_fn, (png_structrp png_ptr,
png_voidp user_chunk_ptr, png_user_chunk_ptr read_user_chunk_fn)); png_voidp user_chunk_ptr, png_user_chunk_ptr read_user_chunk_fn));
@@ -2389,12 +2389,21 @@ PNG_EXPORT(171, void, png_set_sCAL_s, (png_const_structrp png_ptr,
* to specifying "NEVER", however when "AS_DEFAULT" is used for specific chunks * to specifying "NEVER", however when "AS_DEFAULT" is used for specific chunks
* it simply resets the behavior to the libpng default. * it simply resets the behavior to the libpng default.
* *
* INTERACTION WTIH USER CHUNK CALLBACKS:
* The per-chunk handling is always used when there is a png_user_chunk_ptr * The per-chunk handling is always used when there is a png_user_chunk_ptr
* callback and the callback returns 0; the chunk is then always stored *unless* * callback and the callback returns 0; the chunk is then always stored *unless*
* it is critical and the per-chunk setting is other than ALWAYS. Notice that * it is critical and the per-chunk setting is other than ALWAYS. Notice that
* the global default is *not* used in this case. (In effect the per-chunk * the global default is *not* used in this case. (In effect the per-chunk
* value is incremented to at least IF_SAFE.) * value is incremented to at least IF_SAFE.)
* *
* IMPORTANT NOTE: this behavior will change in libpng 1.7 - the global and
* per-chunk defaults will be honored. If you want to preserve the current
* behavior when your callback returns 0 you must set PNG_HANDLE_CHUNK_IF_SAFE
* as the default - if you don't do this libpng 1.6 will issue a warning.
*
* If you want unhandled unknown chunks to be discarded in libpng 1.6 and
* earlier simply return '1' (handled).
*
* PNG_HANDLE_AS_UNKNOWN_SUPPORTED: * PNG_HANDLE_AS_UNKNOWN_SUPPORTED:
* If this is *not* set known chunks will always be handled by libpng and * If this is *not* set known chunks will always be handled by libpng and
* will never be stored in the unknown chunk list. Known chunks listed to * will never be stored in the unknown chunk list. Known chunks listed to