diff --git a/ANNOUNCE b/ANNOUNCE index bbb0e125d..6c2ae40dd 100644 --- a/ANNOUNCE +++ b/ANNOUNCE @@ -68,6 +68,7 @@ Version 1.6.1beta05 [March 1, 2013] Avoid a possible memory leak in contrib/gregbook/readpng.c 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 (subscription required; visit diff --git a/CHANGES b/CHANGES index 02abe3783..d75b9ef80 100644 --- a/CHANGES +++ b/CHANGES @@ -4425,6 +4425,7 @@ Version 1.6.1beta05 [March 1, 2013] Avoid a possible memory leak in contrib/gregbook/readpng.c 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 (subscription required; visit diff --git a/libpng-manual.txt b/libpng-manual.txt index 58858e997..898f09574 100644 --- a/libpng-manual.txt +++ b/libpng-manual.txt @@ -527,9 +527,14 @@ you can retrieve with png_get_user_chunk_ptr(png_ptr); 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 -one or more of them. This behavior can be changed with the -png_set_keep_unknown_chunks() function, described below. +chunks which the callback does not handle will be saved when read. You can +cause them to be discarded by returning '1' ("handled") instead of '0'. This +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 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) - /* ignore all unknown chunks: */ - png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0); + /* ignore all unknown chunks + * (use global setting "2" for libpng16 and earlier): + */ + png_set_keep_unknown_chunks(read_ptr, 2, NULL, 0); /* except for vpAg: */ png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1); diff --git a/libpng.3 b/libpng.3 index 0f5d16a02..dadbb3dbd 100644 --- a/libpng.3 +++ b/libpng.3 @@ -1031,9 +1031,14 @@ you can retrieve with png_get_user_chunk_ptr(png_ptr); 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 -one or more of them. This behavior can be changed with the -png_set_keep_unknown_chunks() function, described below. +chunks which the callback does not handle will be saved when read. You can +cause them to be discarded by returning '1' ("handled") instead of '0'. This +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 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) - /* ignore all unknown chunks: */ - png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0); + /* ignore all unknown chunks + * (use global setting "2" for libpng16 and earlier): + */ + png_set_keep_unknown_chunks(read_ptr, 2, NULL, 0); /* except for vpAg: */ png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1); diff --git a/png.h b/png.h index 0faeb4c8e..a781197f5 100644 --- a/png.h +++ b/png.h @@ -1838,7 +1838,7 @@ PNG_EXPORT(218, png_byte, png_get_current_pass_number, (png_const_structrp)); #endif #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 * 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 @@ -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: * * negative: An error occured, png_chunk_error will be called. - * zero: The chunk was not handled, the chunk will be discarded unless - * png_set_keep_unknown_chunks has been used to set a 'keep' behavior - * 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. + * zero: The chunk was not handled, the chunk will be saved. 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. + * + * 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_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 * 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 * 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 * the global default is *not* used in this case. (In effect the per-chunk * 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: * 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