-.SH VI. Runtime optimization
-
-A new feature in libpng 1.2.0 is the ability to dynamically switch between
-standard and optimized versions of some routines. Currently these are
-limited to three computationally intensive tasks when reading PNG files:
-decoding row filters, expanding interlacing, and combining interlaced or
-transparent row data with previous row data. Currently the optimized
-versions are available only for x86 (Intel, AMD, etc.) platforms with
-MMX support, though this may change in future versions. (For example,
-the non-MMX assembler optimizations for zlib might become similarly
-runtime-selectable in future releases, in which case libpng could be
-extended to support them. Alternatively, the compile-time choice of
-floating-point versus integer routines for gamma correction might become
-runtime-selectable.)
-
-Because such optimizations tend to be very platform- and compiler-dependent,
-both in how they are written and in how they perform, the new runtime code
-in libpng has been written to allow programs to query, enable, and disable
-either specific optimizations or all such optimizations. For example, to
-enable all possible optimizations (bearing in mind that some "optimizations"
-may actually run more slowly in rare cases):
-
- #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
- png_uint_32 mask, flags;
-
- flags = png_get_asm_flags(png_ptr);
- mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
- png_set_asm_flags(png_ptr, flags | mask);
- #endif
-
-To enable only optimizations relevant to reading PNGs, use PNG_SELECT_READ
-by itself when calling png_get_asm_flagmask(); similarly for optimizing
-only writing. To disable all optimizations:
-
- #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
- flags = png_get_asm_flags(png_ptr);
- mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
- png_set_asm_flags(png_ptr, flags & ~mask);
- #endif
-
-To enable or disable only MMX-related features, use png_get_mmx_flagmask()
-in place of png_get_asm_flagmask(). The mmx version takes one additional
-parameter:
-
- #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
- int selection = PNG_SELECT_READ | PNG_SELECT_WRITE;
- int compilerID;
-
- mask = png_get_mmx_flagmask(selection, &compilerID);
- #endif
-
-On return, compilerID will indicate which version of the MMX assembler
-optimizations was compiled. Currently two flavors exist: Microsoft
-Visual C++ (compilerID == 1) and GNU C (a.k.a. gcc/gas, compilerID == 2).
-On non-x86 platforms or on systems compiled without MMX optimizations, a
-value of -1 is used.
-
-Note that both png_get_asm_flagmask() and png_get_mmx_flagmask() return
-all valid, settable optimization bits for the version of the library that's
-currently in use. In the case of shared (dynamically linked) libraries,
-this may include optimizations that did not exist at the time the code was
-written and compiled. It is also possible, of course, to enable only known,
-specific optimizations; for example:
-
- #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
- flags = PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
- | PNG_ASM_FLAG_MMX_READ_INTERLACE \
- | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
- | PNG_ASM_FLAG_MMX_READ_FILTER_UP \
- | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
- | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH ;
- png_set_asm_flags(png_ptr, flags);
- #endif
-
-This method would enable only the MMX read-optimizations available at the
-time of libpng 1.2.0's release, regardless of whether a later version of
-the DLL were actually being used. (Also note that these functions did not
-exist in versions older than 1.2.0, so any attempt to run a dynamically
-linked app on such an older version would fail.)
-
-To determine whether the processor supports MMX instructions at all, use
-the png_mmx_support() function:
-
- #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
- mmxsupport = png_mmx_support();
- #endif
-
-It returns -1 if MMX support is not compiled into libpng, 0 if MMX code
-is compiled but MMX is not supported by the processor, or 1 if MMX support
-is fully available. Note that png_mmx_support(), png_get_mmx_flagmask(),
-and png_get_asm_flagmask() all may be called without allocating and ini-
-tializing any PNG structures (for example, as part of a usage screen or
-"about" box).
-
-The following code can be used to prevent an application from using the
-thread_unsafe features, even if libpng was built with PNG_THREAD_UNSAFE_OK
-defined:
-
-#if defined(PNG_USE_PNGGCCRD) && defined(PNG_ASSEMBLER_CODE_SUPPORTED) \
- && defined(PNG_THREAD_UNSAFE_OK)
- /* Disable thread-unsafe features of pnggccrd */
- if (png_access_version() >= 10200)
- {
- png_uint_32 mmx_disable_mask = 0;
- png_uint_32 asm_flags;
-
- mmx_disable_mask |= ( PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
- | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
- | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
- | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH );
- asm_flags = png_get_asm_flags(png_ptr);
- png_set_asm_flags(png_ptr, asm_flags & ~mmx_disable_mask);
- }
-#endif
-
-For more extensive examples of runtime querying, enabling and disabling
-of optimized features, see contrib/gregbook/readpng2.c in the libpng
-source-code distribution.
-
projects / wxWidgets.git / blobdiff