1085
1085
png_set_read_status_fn(png_ptr, read_row_callback);
1087
.SS Width and height limits
1089
The PNG specification allows the width and height of an image to be as
1090
large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
1091
Since very few applications really need to process such large images,
1092
we have imposed an arbitrary 1-million limit on rows and columns.
1093
Larger images will be rejected immediately with a png_error() call. If
1094
you wish to override this limit, you can use
1096
png_set_user_limits(png_ptr, width_max, height_max);
1098
to set your own limits, or use width_max = height_max = 0x7fffffffL
1099
to allow all valid dimensions (libpng may reject some very large images
1100
anyway because of potential buffer overflow conditions).
1102
You should put this statement after you create the PNG structure and
1103
before calling png_read_info(), png_read_png(), or png_process_data().
1104
If you need to retrieve the limits that are being applied, use
1106
width_max = png_get_user_width_max(png_ptr);
1107
height_max = png_get_user_height_max(png_ptr);
1087
1109
.SS Unknown-chunk handling
1089
1111
Now you get to set the way the library processes unknown chunks in the
3459
3490
having level = 0 will be printed. There aren't any such statements in
3460
3491
this version of libpng, but if you insert some they will be printed.
3493
.SH VI. Runtime optimization
3495
A new feature in libpng 1.2.0 is the ability to dynamically switch between
3496
standard and optimized versions of some routines. Currently these are
3497
limited to three computationally intensive tasks when reading PNG files:
3498
decoding row filters, expanding interlacing, and combining interlaced or
3499
transparent row data with previous row data. Currently the optimized
3500
versions are available only for x86 (Intel, AMD, etc.) platforms with
3501
MMX support, though this may change in future versions. (For example,
3502
the non-MMX assembler optimizations for zlib might become similarly
3503
runtime-selectable in future releases, in which case libpng could be
3504
extended to support them. Alternatively, the compile-time choice of
3505
floating-point versus integer routines for gamma correction might become
3506
runtime-selectable.)
3508
Because such optimizations tend to be very platform- and compiler-dependent,
3509
both in how they are written and in how they perform, the new runtime code
3510
in libpng has been written to allow programs to query, enable, and disable
3511
either specific optimizations or all such optimizations. For example, to
3512
enable all possible optimizations (bearing in mind that some "optimizations"
3513
may actually run more slowly in rare cases):
3515
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3516
png_uint_32 mask, flags;
3518
flags = png_get_asm_flags(png_ptr);
3519
mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
3520
png_set_asm_flags(png_ptr, flags | mask);
3523
To enable only optimizations relevant to reading PNGs, use PNG_SELECT_READ
3524
by itself when calling png_get_asm_flagmask(); similarly for optimizing
3525
only writing. To disable all optimizations:
3527
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3528
flags = png_get_asm_flags(png_ptr);
3529
mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
3530
png_set_asm_flags(png_ptr, flags & ~mask);
3533
To enable or disable only MMX-related features, use png_get_mmx_flagmask()
3534
in place of png_get_asm_flagmask(). The mmx version takes one additional
3537
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3538
int selection = PNG_SELECT_READ | PNG_SELECT_WRITE;
3541
mask = png_get_mmx_flagmask(selection, &compilerID);
3544
On return, compilerID will indicate which version of the MMX assembler
3545
optimizations was compiled. Currently two flavors exist: Microsoft
3546
Visual C++ (compilerID == 1) and GNU C (a.k.a. gcc/gas, compilerID == 2).
3547
On non-x86 platforms or on systems compiled without MMX optimizations, a
3548
value of -1 is used.
3550
Note that both png_get_asm_flagmask() and png_get_mmx_flagmask() return
3551
all valid, settable optimization bits for the version of the library that's
3552
currently in use. In the case of shared (dynamically linked) libraries,
3553
this may include optimizations that did not exist at the time the code was
3554
written and compiled. It is also possible, of course, to enable only known,
3555
specific optimizations; for example:
3557
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3558
flags = PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
3559
| PNG_ASM_FLAG_MMX_READ_INTERLACE \
3560
| PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
3561
| PNG_ASM_FLAG_MMX_READ_FILTER_UP \
3562
| PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
3563
| PNG_ASM_FLAG_MMX_READ_FILTER_PAETH ;
3564
png_set_asm_flags(png_ptr, flags);
3567
This method would enable only the MMX read-optimizations available at the
3568
time of libpng 1.2.0's release, regardless of whether a later version of
3569
the DLL were actually being used. (Also note that these functions did not
3570
exist in versions older than 1.2.0, so any attempt to run a dynamically
3571
linked app on such an older version would fail.)
3573
To determine whether the processor supports MMX instructions at all, use
3574
the png_mmx_support() function:
3576
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3577
mmxsupport = png_mmx_support();
3580
It returns -1 if MMX support is not compiled into libpng, 0 if MMX code
3581
is compiled but MMX is not supported by the processor, or 1 if MMX support
3582
is fully available. Note that png_mmx_support(), png_get_mmx_flagmask(),
3583
and png_get_asm_flagmask() all may be called without allocating and ini-
3584
tializing any PNG structures (for example, as part of a usage screen or
3587
The following code can be used to prevent an application from using the
3588
thread_unsafe features, even if libpng was built with PNG_THREAD_UNSAFE_OK
3591
#if defined(PNG_USE_PNGGCCRD) && defined(PNG_ASSEMBLER_CODE_SUPPORTED) \
3592
&& defined(PNG_THREAD_UNSAFE_OK)
3593
/* Disable thread-unsafe features of pnggccrd */
3594
if (png_access_version() >= 10200)
3596
png_uint_32 mmx_disable_mask = 0;
3597
png_uint_32 asm_flags;
3599
mmx_disable_mask |= ( PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
3600
| PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
3601
| PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
3602
| PNG_ASM_FLAG_MMX_READ_FILTER_PAETH );
3603
asm_flags = png_get_asm_flags(png_ptr);
3604
png_set_asm_flags(png_ptr, asm_flags & ~mmx_disable_mask);
3608
For more extensive examples of runtime querying, enabling and disabling
3609
of optimized features, see contrib/gregbook/readpng2.c in the libpng
3610
source-code distribution.
3612
.SH VII. MNG support
3464
3614
The MNG specification (available at http://www.libpng.org/pub/mng) allows
3465
3615
certain extensions to PNG for PNG images that are embedded in MNG datastreams.