304
304
png_set_read_status_fn(png_ptr, read_row_callback);
306
Width and height limits
308
The PNG specification allows the width and height of an image to be as
309
large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
310
Since very few applications really need to process such large images,
311
we have imposed an arbitrary 1-million limit on rows and columns.
312
Larger images will be rejected immediately with a png_error() call. If
313
you wish to override this limit, you can use
315
png_set_user_limits(png_ptr, width_max, height_max);
317
to set your own limits, or use width_max = height_max = 0x7fffffffL
318
to allow all valid dimensions (libpng may reject some very large images
319
anyway because of potential buffer overflow conditions).
321
You should put this statement after you create the PNG structure and
322
before calling png_read_info(), png_read_png(), or png_process_data().
323
If you need to retrieve the limits that are being applied, use
325
width_max = png_get_user_width_max(png_ptr);
326
height_max = png_get_user_height_max(png_ptr);
306
328
Unknown-chunk handling
308
330
Now you get to set the way the library processes unknown chunks in the
2678
2709
having level = 0 will be printed. There aren't any such statements in
2679
2710
this version of libpng, but if you insert some they will be printed.
2712
VI. Runtime optimization
2714
A new feature in libpng 1.2.0 is the ability to dynamically switch between
2715
standard and optimized versions of some routines. Currently these are
2716
limited to three computationally intensive tasks when reading PNG files:
2717
decoding row filters, expanding interlacing, and combining interlaced or
2718
transparent row data with previous row data. Currently the optimized
2719
versions are available only for x86 (Intel, AMD, etc.) platforms with
2720
MMX support, though this may change in future versions. (For example,
2721
the non-MMX assembler optimizations for zlib might become similarly
2722
runtime-selectable in future releases, in which case libpng could be
2723
extended to support them. Alternatively, the compile-time choice of
2724
floating-point versus integer routines for gamma correction might become
2725
runtime-selectable.)
2727
Because such optimizations tend to be very platform- and compiler-dependent,
2728
both in how they are written and in how they perform, the new runtime code
2729
in libpng has been written to allow programs to query, enable, and disable
2730
either specific optimizations or all such optimizations. For example, to
2731
enable all possible optimizations (bearing in mind that some "optimizations"
2732
may actually run more slowly in rare cases):
2734
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
2735
png_uint_32 mask, flags;
2737
flags = png_get_asm_flags(png_ptr);
2738
mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
2739
png_set_asm_flags(png_ptr, flags | mask);
2742
To enable only optimizations relevant to reading PNGs, use PNG_SELECT_READ
2743
by itself when calling png_get_asm_flagmask(); similarly for optimizing
2744
only writing. To disable all optimizations:
2746
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
2747
flags = png_get_asm_flags(png_ptr);
2748
mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
2749
png_set_asm_flags(png_ptr, flags & ~mask);
2752
To enable or disable only MMX-related features, use png_get_mmx_flagmask()
2753
in place of png_get_asm_flagmask(). The mmx version takes one additional
2756
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
2757
int selection = PNG_SELECT_READ | PNG_SELECT_WRITE;
2760
mask = png_get_mmx_flagmask(selection, &compilerID);
2763
On return, compilerID will indicate which version of the MMX assembler
2764
optimizations was compiled. Currently two flavors exist: Microsoft
2765
Visual C++ (compilerID == 1) and GNU C (a.k.a. gcc/gas, compilerID == 2).
2766
On non-x86 platforms or on systems compiled without MMX optimizations, a
2767
value of -1 is used.
2769
Note that both png_get_asm_flagmask() and png_get_mmx_flagmask() return
2770
all valid, settable optimization bits for the version of the library that's
2771
currently in use. In the case of shared (dynamically linked) libraries,
2772
this may include optimizations that did not exist at the time the code was
2773
written and compiled. It is also possible, of course, to enable only known,
2774
specific optimizations; for example:
2776
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
2777
flags = PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
2778
| PNG_ASM_FLAG_MMX_READ_INTERLACE \
2779
| PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
2780
| PNG_ASM_FLAG_MMX_READ_FILTER_UP \
2781
| PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
2782
| PNG_ASM_FLAG_MMX_READ_FILTER_PAETH ;
2783
png_set_asm_flags(png_ptr, flags);
2786
This method would enable only the MMX read-optimizations available at the
2787
time of libpng 1.2.0's release, regardless of whether a later version of
2788
the DLL were actually being used. (Also note that these functions did not
2789
exist in versions older than 1.2.0, so any attempt to run a dynamically
2790
linked app on such an older version would fail.)
2792
To determine whether the processor supports MMX instructions at all, use
2793
the png_mmx_support() function:
2795
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
2796
mmxsupport = png_mmx_support();
2799
It returns -1 if MMX support is not compiled into libpng, 0 if MMX code
2800
is compiled but MMX is not supported by the processor, or 1 if MMX support
2801
is fully available. Note that png_mmx_support(), png_get_mmx_flagmask(),
2802
and png_get_asm_flagmask() all may be called without allocating and ini-
2803
tializing any PNG structures (for example, as part of a usage screen or
2806
The following code can be used to prevent an application from using the
2807
thread_unsafe features, even if libpng was built with PNG_THREAD_UNSAFE_OK
2810
#if defined(PNG_USE_PNGGCCRD) && defined(PNG_ASSEMBLER_CODE_SUPPORTED) \
2811
&& defined(PNG_THREAD_UNSAFE_OK)
2812
/* Disable thread-unsafe features of pnggccrd */
2813
if (png_access_version() >= 10200)
2815
png_uint_32 mmx_disable_mask = 0;
2816
png_uint_32 asm_flags;
2818
mmx_disable_mask |= ( PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
2819
| PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
2820
| PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
2821
| PNG_ASM_FLAG_MMX_READ_FILTER_PAETH );
2822
asm_flags = png_get_asm_flags(png_ptr);
2823
png_set_asm_flags(png_ptr, asm_flags & ~mmx_disable_mask);
2827
For more extensive examples of runtime querying, enabling and disabling
2828
of optimized features, see contrib/gregbook/readpng2.c in the libpng
2829
source-code distribution.
2683
2833
The MNG specification (available at http://www.libpng.org/pub/mng) allows
2684
2834
certain extensions to PNG for PNG images that are embedded in MNG datastreams.