libpng.txt - A description on how to use and modify libpng
- libpng version 1.2.5rc3 - September 18, 2002
+ libpng version 1.2.6 - August 15, 2004
Updated and distributed by Glenn Randers-Pehrson
- <randeg@alum.rpi.edu>
- Copyright (c) 1998-2002 Glenn Randers-Pehrson
+ <glennrp@users.sourceforge.net>
+ Copyright (c) 1998-2004 Glenn Randers-Pehrson
For conditions of distribution and use, see copyright
notice in png.h.
png_set_read_status_fn(png_ptr, read_row_callback);
+Width and height limits
+
+The PNG specification allows the width and height of an image to be as
+large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
+Since very few applications really need to process such large images,
+we have imposed an arbitrary 1-million limit on rows and columns.
+Larger images will be rejected immediately with a png_error() call. If
+you wish to override this limit, you can use
+
+ png_set_user_limits(png_ptr, width_max, height_max);
+
+to set your own limits, or use width_max = height_max = 0x7fffffffL
+to allow all valid dimensions (libpng may reject some very large images
+anyway because of potential buffer overflow conditions).
+
+You should put this statement after you create the PNG structure and
+before calling png_read_info(), png_read_png(), or png_process_data().
+If you need to retrieve the limits that are being applied, use
+
+ width_max = png_get_user_width_max(png_ptr);
+ height_max = png_get_user_height_max(png_ptr);
+
Unknown-chunk handling
Now you get to set the way the library processes unknown chunks in the
various info_ptr members; unknown chunks will be discarded. To change
this, you can call:
- png_set_keep_unknown_chunks(png_ptr, info_ptr, keep,
+ png_set_keep_unknown_chunks(png_ptr, keep,
chunk_list, num_chunks);
- keep - 0: do not keep
- 1: keep only if safe-to-copy
- 2: keep even if unsafe-to-copy
+ keep - 0: do not handle as unknown
+ 1: do not keep
+ 2: keep only if safe-to-copy
+ 3: keep even if unsafe-to-copy
+ You can use these definitions:
+ PNG_HANDLE_CHUNK_AS_DEFAULT 0
+ PNG_HANDLE_CHUNK_NEVER 1
+ PNG_HANDLE_CHUNK_IF_SAFE 2
+ PNG_HANDLE_CHUNK_ALWAYS 3
chunk_list - list of chunks affected (a byte string,
five bytes per chunk, NULL or '\0' if
num_chunks is 0)
num_chunks - number of chunks affected; if 0, all
- unknown chunks are affected
+ unknown chunks are affected. If nonzero,
+ only the chunks in the list are affected
Unknown chunks declared in this way will be saved as raw data onto a
list of png_unknown_chunk structures. If a chunk that is normally
known to libpng is named in the list, it will be handled as unknown,
according to the "keep" directive. If a chunk is named in successive
instances of png_set_keep_unknown_chunks(), the final instance will
-take precedence.
+take precedence. The IHDR and IEND chunks should not be named in
+chunk_list; if they are, libpng will process them normally anyway.
The high-level read interface
If you know your image size and pixel size ahead of time, you can allocate
row_pointers prior to calling png_read_png() with
+ if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
+ png_error (png_ptr,
+ "Image is too tall to process in memory");
+ if (width > PNG_UINT_32_MAX/pixel_size)
+ png_error (png_ptr,
+ "Image is too wide to process in memory");
row_pointers = png_malloc(png_ptr,
- height*sizeof(png_bytep));
+ height*png_sizeof(png_bytep));
for (int i=0; i<height, i++)
row_pointers[i]=png_malloc(png_ptr,
width*pixel_size);
to use a different method of allocating and freeing data, you can use
png_create_read_struct_2() or png_create_write_struct_2() to register
your own functions as described above.
-
These functions also provide a void pointer that can be retrieved via
mem_ptr=png_get_mem_ptr(png_ptr);
png_size_t size);
void free_fn(png_structp png_ptr, png_voidp ptr);
-Your malloc_fn() should return NULL in case of failure. The png_malloc()
-function will call png_error() if it receives a NULL from the system
-memory allocator or from your replacement malloc_fn().
+Your malloc_fn() must return NULL in case of failure. The png_malloc()
+function will normally call png_error() if it receives a NULL from the
+system memory allocator or from your replacement malloc_fn().
Input/Output in libpng is done through png_read() and png_write(),
which currently just call fread() and fwrite(). The FILE * is stored in
of optimized features, see contrib/gregbook/readpng2.c in the libpng
source-code distribution.
-
-VII. MNG support
+VI. MNG support
The MNG specification (available at http://www.libpng.org/pub/mng) allows
certain extensions to PNG for PNG images that are embedded in MNG datastreams.
PNG_FLAG_MNG_EMPTY_PLTE
PNG_FLAG_MNG_FILTER_64
PNG_ALL_MNG_FEATURES
- feature_set is a png_32_uint that is the logical AND of
+ feature_set is a png_uint_32 that is the logical AND of
your mask with the set of MNG features that is
supported by the version of libpng that you are using.
them. You may wish to consider using libmng (available at
http://www.libmng.com) instead.
-VIII. Changes to Libpng from version 0.88
+VII. Changes to Libpng from version 0.88
It should be noted that versions of libpng later than 0.96 are not
distributed by the original libpng author, Guy Schalnat, nor by
png_uint_32 application_vn = PNG_LIBPNG_VER;
-IX. Y2K Compliance in libpng
+VII. Y2K Compliance in libpng
-September 18, 2002
+August 15, 2004
Since the PNG Development group is an ad-hoc body, we can't make
an official declaration.
This is your unofficial assurance that libpng from version 0.71 and
-upward through 1.2.5rc3 are Y2K compliant. It is my belief that earlier
+upward through 1.2.6 are Y2K compliant. It is my belief that earlier
versions were also Y2K compliant.
Libpng only has three year fields. One is a 2-byte unsigned integer that
projects / wxWidgets.git / blobdiff