[devel] Added more about creating and destroying the optional "end_info"
structure in the libpng documentation.
This commit is contained in:
Glenn Randers-Pehrson
parent
99778e17af
commit
20786be695
@ -1,6 +1,6 @@
|
||||
libpng-manual.txt - A description on how to use and modify libpng
|
||||
|
||||
libpng version 1.5.3beta04 - April 20, 2011
|
||||
libpng version 1.5.3beta04 - April 21, 2011
|
||||
Updated and distributed by Glenn Randers-Pehrson
|
||||
<glennrp at users.sourceforge.net>
|
||||
Copyright (c) 1998-2011 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.5.3beta04 - April 20, 2011
|
||||
libpng versions 0.97, January 1998, through 1.5.3beta04 - April 21, 2011
|
||||
Updated and distributed by Glenn Randers-Pehrson
|
||||
Copyright (c) 1998-2011 Glenn Randers-Pehrson
|
||||
|
||||
@ -348,21 +348,12 @@ create the structure, so your application should check for that.
|
||||
return (ERROR);
|
||||
}
|
||||
|
||||
png_infop end_info = png_create_info_struct(png_ptr);
|
||||
|
||||
if (!end_info)
|
||||
{
|
||||
png_destroy_read_struct(&png_ptr, &info_ptr,
|
||||
(png_infopp)NULL);
|
||||
return (ERROR);
|
||||
}
|
||||
|
||||
If you want to use your own memory allocation routines,
|
||||
use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use
|
||||
png_create_read_struct_2() instead of png_create_read_struct():
|
||||
|
||||
png_structp png_ptr = png_create_read_struct_2
|
||||
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
|
||||
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
|
||||
user_error_fn, user_warning_fn, (png_voidp)
|
||||
user_mem_ptr, user_malloc_fn, user_free_fn);
|
||||
|
||||
@ -392,6 +383,9 @@ free any memory.
|
||||
return (ERROR);
|
||||
}
|
||||
|
||||
Pass (png_infopp)NULL instead of &end_info if you didn't create
|
||||
an end_info structure.
|
||||
|
||||
If you would rather avoid the complexity of setjmp/longjmp issues,
|
||||
you can compile libpng with PNG_NO_SETJMP, in which case
|
||||
errors will result in a call to PNG_ABORT() which defaults to abort().
|
||||
@ -1824,11 +1818,24 @@ low-level interface, you can finish reading the file. If you are
|
||||
interested in comments or time, which may be stored either before or
|
||||
after the image data, you should pass the separate png_info struct if
|
||||
you want to keep the comments from before and after the image
|
||||
separate. If you are not interested, you should still call png_read_end()
|
||||
but you can pass NULL, avoiding the need to create an end_info structure.
|
||||
separate.
|
||||
|
||||
png_infop end_info = png_create_info_struct(png_ptr);
|
||||
|
||||
if (!end_info)
|
||||
{
|
||||
png_destroy_read_struct(&png_ptr, &info_ptr,
|
||||
(png_infopp)NULL);
|
||||
return (ERROR);
|
||||
}
|
||||
|
||||
png_read_end(png_ptr, end_info);
|
||||
|
||||
If you are not interested, you should still call png_read_end()
|
||||
but you can pass NULL, avoiding the need to create an end_info structure.
|
||||
|
||||
png_read_end(png_ptr, (png_infop)NULL);
|
||||
|
||||
If you don't call png_read_end(), then your file pointer will be
|
||||
left pointing to the first chunk after the last IDAT, which is probably
|
||||
not what you want if you expect to read something beyond the end of
|
||||
@ -1839,6 +1846,11 @@ When you are done, you can free all memory allocated by libpng like this:
|
||||
png_destroy_read_struct(&png_ptr, &info_ptr,
|
||||
&end_info);
|
||||
|
||||
or, if you didn't create an end_info structure,
|
||||
|
||||
png_destroy_read_struct(&png_ptr, &info_ptr,
|
||||
(png_infopp)NULL);
|
||||
|
||||
It is also possible to individually free the info_ptr members that
|
||||
point to libpng-allocated storage with the following function:
|
||||
|
||||
@ -4180,7 +4192,7 @@ Other rules can be inferred by inspecting the libpng source.
|
||||
|
||||
XIV. Y2K Compliance in libpng
|
||||
|
||||
April 20, 2011
|
||||
April 21, 2011
|
||||
|
||||
Since the PNG Development group is an ad-hoc body, we can't make
|
||||
an official declaration.
|
||||
|
||||
50
libpng.3
50
libpng.3
@ -1,4 +1,4 @@
|
||||
.TH LIBPNG 3 "April 20, 2011"
|
||||
.TH LIBPNG 3 "April 21, 2011"
|
||||
.SH NAME
|
||||
libpng \- Portable Network Graphics (PNG) Reference Library 1.5.3beta04
|
||||
.SH SYNOPSIS
|
||||
@ -943,7 +943,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.5.3beta04 - April 20, 2011
|
||||
libpng version 1.5.3beta04 - April 21, 2011
|
||||
Updated and distributed by Glenn Randers-Pehrson
|
||||
<glennrp at users.sourceforge.net>
|
||||
Copyright (c) 1998-2011 Glenn Randers-Pehrson
|
||||
@ -954,7 +954,7 @@ libpng-manual.txt - A description on how to use and modify libpng
|
||||
|
||||
Based on:
|
||||
|
||||
libpng versions 0.97, January 1998, through 1.5.3beta04 - April 20, 2011
|
||||
libpng versions 0.97, January 1998, through 1.5.3beta04 - April 21, 2011
|
||||
Updated and distributed by Glenn Randers-Pehrson
|
||||
Copyright (c) 1998-2011 Glenn Randers-Pehrson
|
||||
|
||||
@ -1291,21 +1291,12 @@ create the structure, so your application should check for that.
|
||||
return (ERROR);
|
||||
}
|
||||
|
||||
png_infop end_info = png_create_info_struct(png_ptr);
|
||||
|
||||
if (!end_info)
|
||||
{
|
||||
png_destroy_read_struct(&png_ptr, &info_ptr,
|
||||
(png_infopp)NULL);
|
||||
return (ERROR);
|
||||
}
|
||||
|
||||
If you want to use your own memory allocation routines,
|
||||
use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use
|
||||
png_create_read_struct_2() instead of png_create_read_struct():
|
||||
|
||||
png_structp png_ptr = png_create_read_struct_2
|
||||
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
|
||||
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
|
||||
user_error_fn, user_warning_fn, (png_voidp)
|
||||
user_mem_ptr, user_malloc_fn, user_free_fn);
|
||||
|
||||
@ -1335,6 +1326,9 @@ free any memory.
|
||||
return (ERROR);
|
||||
}
|
||||
|
||||
Pass (png_infopp)NULL instead of &end_info if you didn't create
|
||||
an end_info structure.
|
||||
|
||||
If you would rather avoid the complexity of setjmp/longjmp issues,
|
||||
you can compile libpng with PNG_NO_SETJMP, in which case
|
||||
errors will result in a call to PNG_ABORT() which defaults to abort().
|
||||
@ -2767,11 +2761,24 @@ low-level interface, you can finish reading the file. If you are
|
||||
interested in comments or time, which may be stored either before or
|
||||
after the image data, you should pass the separate png_info struct if
|
||||
you want to keep the comments from before and after the image
|
||||
separate. If you are not interested, you should still call png_read_end()
|
||||
but you can pass NULL, avoiding the need to create an end_info structure.
|
||||
separate.
|
||||
|
||||
png_infop end_info = png_create_info_struct(png_ptr);
|
||||
|
||||
if (!end_info)
|
||||
{
|
||||
png_destroy_read_struct(&png_ptr, &info_ptr,
|
||||
(png_infopp)NULL);
|
||||
return (ERROR);
|
||||
}
|
||||
|
||||
png_read_end(png_ptr, end_info);
|
||||
|
||||
If you are not interested, you should still call png_read_end()
|
||||
but you can pass NULL, avoiding the need to create an end_info structure.
|
||||
|
||||
png_read_end(png_ptr, (png_infop)NULL);
|
||||
|
||||
If you don't call png_read_end(), then your file pointer will be
|
||||
left pointing to the first chunk after the last IDAT, which is probably
|
||||
not what you want if you expect to read something beyond the end of
|
||||
@ -2782,6 +2789,11 @@ When you are done, you can free all memory allocated by libpng like this:
|
||||
png_destroy_read_struct(&png_ptr, &info_ptr,
|
||||
&end_info);
|
||||
|
||||
or, if you didn't create an end_info structure,
|
||||
|
||||
png_destroy_read_struct(&png_ptr, &info_ptr,
|
||||
(png_infopp)NULL);
|
||||
|
||||
It is also possible to individually free the info_ptr members that
|
||||
point to libpng-allocated storage with the following function:
|
||||
|
||||
@ -5123,7 +5135,7 @@ Other rules can be inferred by inspecting the libpng source.
|
||||
|
||||
.SH XIV. Y2K Compliance in libpng
|
||||
|
||||
April 20, 2011
|
||||
April 21, 2011
|
||||
|
||||
Since the PNG Development group is an ad-hoc body, we can't make
|
||||
an official declaration.
|
||||
@ -5375,7 +5387,7 @@ possible without all of you.
|
||||
|
||||
Thanks to Frank J. T. Wojcik for helping with the documentation.
|
||||
|
||||
Libpng version 1.5.3beta04 - April 20, 2011:
|
||||
Libpng version 1.5.3beta04 - April 21, 2011:
|
||||
Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
|
||||
Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
|
||||
|
||||
@ -5398,7 +5410,7 @@ this sentence.
|
||||
|
||||
This code is released under the libpng license.
|
||||
|
||||
libpng versions 1.2.6, August 15, 2004, through 1.5.3beta04, April 20, 2011, are
|
||||
libpng versions 1.2.6, August 15, 2004, through 1.5.3beta04, April 21, 2011, 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
|
||||
@ -5497,7 +5509,7 @@ certification mark of the Open Source Initiative.
|
||||
|
||||
Glenn Randers-Pehrson
|
||||
glennrp at users.sourceforge.net
|
||||
April 20, 2011
|
||||
April 21, 2011
|
||||
|
||||
.\" end of man page
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user