mirror of
https://git.code.sf.net/p/libpng/code.git
synced 2025-07-10 18:04:09 +02:00
[libpng16] Better documentation of unknown handling API interactions.
This commit is contained in:
John Bowler
Glenn Randers-Pehrson
parent
e57f094fd6
commit
e15b537825
1
ANNOUNCE
1
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
|
||||
|
||||
1
CHANGES
1
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
|
||||
|
||||
@ -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);
|
||||
|
||||
17
libpng.3
17
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);
|
||||
|
||||
21
png.h
21
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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user