summaryrefslogtreecommitdiffstats
path: root/media/libwebp/README
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--media/libwebp/README789
-rw-r--r--media/libwebp/README.mux256
2 files changed, 1045 insertions, 0 deletions
diff --git a/media/libwebp/README b/media/libwebp/README
new file mode 100644
index 0000000000..059272763e
--- /dev/null
+++ b/media/libwebp/README
@@ -0,0 +1,789 @@
+ __ __ ____ ____ ____
+ / \\/ \/ _ \/ _ )/ _ \
+ \ / __/ _ \ __/
+ \__\__/\____/\_____/__/ ____ ___
+ / _/ / \ \ / _ \/ _/
+ / \_/ / / \ \ __/ \__
+ \____/____/\_____/_____/____/v1.1.0
+
+Description:
+============
+
+WebP codec: library to encode and decode images in WebP format. This package
+contains the library that can be used in other programs to add WebP support,
+as well as the command line tools 'cwebp' and 'dwebp'.
+
+See http://developers.google.com/speed/webp
+
+The latest source tree is available at
+https://chromium.googlesource.com/webm/libwebp
+
+It is released under the same license as the WebM project.
+See http://www.webmproject.org/license/software/ or the
+"COPYING" file for details. An additional intellectual
+property rights grant can be found in the file PATENTS.
+
+Building:
+=========
+
+Windows build:
+--------------
+
+By running:
+
+ nmake /f Makefile.vc CFG=release-static RTLIBCFG=static OBJDIR=output
+
+the directory output\release-static\(x64|x86)\bin will contain the tools
+cwebp.exe and dwebp.exe. The directory output\release-static\(x64|x86)\lib will
+contain the libwebp static library.
+The target architecture (x86/x64) is detected by Makefile.vc from the Visual
+Studio compiler (cl.exe) available in the system path.
+
+Unix build using makefile.unix:
+-------------------------------
+
+On platforms with GNU tools installed (gcc and make), running
+
+ make -f makefile.unix
+
+will build the binaries examples/cwebp and examples/dwebp, along
+with the static library src/libwebp.a. No system-wide installation
+is supplied, as this is a simple alternative to the full installation
+system based on the autoconf tools (see below).
+Please refer to makefile.unix for additional details and customizations.
+
+Using autoconf tools:
+---------------------
+Prerequisites:
+A compiler (e.g., gcc), make, autoconf, automake, libtool.
+On a Debian-like system the following should install everything you need for a
+minimal build:
+$ sudo apt-get install gcc make autoconf automake libtool
+
+When building from git sources, you will need to run autogen.sh to generate the
+configure script.
+
+./configure
+make
+make install
+
+should be all you need to have the following files
+
+/usr/local/include/webp/decode.h
+/usr/local/include/webp/encode.h
+/usr/local/include/webp/types.h
+/usr/local/lib/libwebp.*
+/usr/local/bin/cwebp
+/usr/local/bin/dwebp
+
+installed.
+
+Note: A decode-only library, libwebpdecoder, is available using the
+'--enable-libwebpdecoder' flag. The encode library is built separately and can
+be installed independently using a minor modification in the corresponding
+Makefile.am configure files (see comments there). See './configure --help' for
+more options.
+
+Building for MIPS Linux:
+------------------------
+MIPS Linux toolchain stable available releases can be found at:
+https://community.imgtec.com/developers/mips/tools/codescape-mips-sdk/available-releases/
+
+# Add toolchain to PATH
+export PATH=$PATH:/path/to/toolchain/bin
+
+# 32-bit build for mips32r5 (p5600)
+HOST=mips-mti-linux-gnu
+MIPS_CFLAGS="-O3 -mips32r5 -mabi=32 -mtune=p5600 -mmsa -mfp64 \
+ -msched-weight -mload-store-pairs -fPIE"
+MIPS_LDFLAGS="-mips32r5 -mabi=32 -mmsa -mfp64 -pie"
+
+# 64-bit build for mips64r6 (i6400)
+HOST=mips-img-linux-gnu
+MIPS_CFLAGS="-O3 -mips64r6 -mabi=64 -mtune=i6400 -mmsa -mfp64 \
+ -msched-weight -mload-store-pairs -fPIE"
+MIPS_LDFLAGS="-mips64r6 -mabi=64 -mmsa -mfp64 -pie"
+
+./configure --host=${HOST} --build=`config.guess` \
+ CC="${HOST}-gcc -EL" \
+ CFLAGS="$MIPS_CFLAGS" \
+ LDFLAGS="$MIPS_LDFLAGS"
+make
+make install
+
+CMake:
+------
+With CMake, you can compile libwebp, cwebp, dwebp, gif2web, img2webp, webpinfo
+and the JS bindings.
+
+Prerequisites:
+A compiler (e.g., gcc with autotools) and CMake.
+On a Debian-like system the following should install everything you need for a
+minimal build:
+$ sudo apt-get install build-essential cmake
+
+When building from git sources, you will need to run cmake to generate the
+makefiles.
+
+mkdir build && cd build && cmake ../
+make
+make install
+
+If you also want any of the executables, you will need to enable them through
+CMake, e.g.:
+
+cmake -DWEBP_BUILD_CWEBP=ON -DWEBP_BUILD_DWEBP=ON ../
+
+or through your favorite interface (like ccmake or cmake-qt-gui).
+
+Use option -DWEBP_UNICODE=ON for Unicode support on Windows (with chcp 65001).
+
+Finally, once installed, you can also use WebP in your CMake project by doing:
+
+find_package(WebP)
+
+which will define the CMake variables WebP_INCLUDE_DIRS and WebP_LIBRARIES.
+
+Gradle:
+-------
+The support for Gradle is minimal: it only helps you compile libwebp, cwebp and
+dwebp and webpmux_example.
+
+Prerequisites:
+A compiler (e.g., gcc with autotools) and gradle.
+On a Debian-like system the following should install everything you need for a
+minimal build:
+$ sudo apt-get install build-essential gradle
+
+When building from git sources, you will need to run the Gradle wrapper with the
+appropriate target, e.g. :
+
+./gradlew buildAllExecutables
+
+SWIG bindings:
+--------------
+
+To generate language bindings from swig/libwebp.swig at least swig-1.3
+(http://www.swig.org) is required.
+
+Currently the following functions are mapped:
+Decode:
+ WebPGetDecoderVersion
+ WebPGetInfo
+ WebPDecodeRGBA
+ WebPDecodeARGB
+ WebPDecodeBGRA
+ WebPDecodeBGR
+ WebPDecodeRGB
+
+Encode:
+ WebPGetEncoderVersion
+ WebPEncodeRGBA
+ WebPEncodeBGRA
+ WebPEncodeRGB
+ WebPEncodeBGR
+ WebPEncodeLosslessRGBA
+ WebPEncodeLosslessBGRA
+ WebPEncodeLosslessRGB
+ WebPEncodeLosslessBGR
+
+See swig/README for more detailed build instructions.
+
+Java bindings:
+
+To build the swig-generated JNI wrapper code at least JDK-1.5 (or equivalent)
+is necessary for enum support. The output is intended to be a shared object /
+DLL that can be loaded via System.loadLibrary("webp_jni").
+
+Python bindings:
+
+To build the swig-generated Python extension code at least Python 2.6 is
+required. Python < 2.6 may build with some minor changes to libwebp.swig or the
+generated code, but is untested.
+
+Encoding tool:
+==============
+
+The examples/ directory contains tools for encoding (cwebp) and
+decoding (dwebp) images.
+
+The easiest use should look like:
+ cwebp input.png -q 80 -o output.webp
+which will convert the input file to a WebP file using a quality factor of 80
+on a 0->100 scale (0 being the lowest quality, 100 being the best. Default
+value is 75).
+You might want to try the -lossless flag too, which will compress the source
+(in RGBA format) without any loss. The -q quality parameter will in this case
+control the amount of processing time spent trying to make the output file as
+small as possible.
+
+A longer list of options is available using the -longhelp command line flag:
+
+> cwebp -longhelp
+Usage:
+ cwebp [-preset <...>] [options] in_file [-o out_file]
+
+If input size (-s) for an image is not specified, it is
+assumed to be a PNG, JPEG, TIFF or WebP file.
+
+Options:
+ -h / -help ............. short help
+ -H / -longhelp ......... long help
+ -q <float> ............. quality factor (0:small..100:big), default=75
+ -alpha_q <int> ......... transparency-compression quality (0..100),
+ default=100
+ -preset <string> ....... preset setting, one of:
+ default, photo, picture,
+ drawing, icon, text
+ -preset must come first, as it overwrites other parameters
+ -z <int> ............... activates lossless preset with given
+ level in [0:fast, ..., 9:slowest]
+
+ -m <int> ............... compression method (0=fast, 6=slowest), default=4
+ -segments <int> ........ number of segments to use (1..4), default=4
+ -size <int> ............ target size (in bytes)
+ -psnr <float> .......... target PSNR (in dB. typically: 42)
+
+ -s <int> <int> ......... input size (width x height) for YUV
+ -sns <int> ............. spatial noise shaping (0:off, 100:max), default=50
+ -f <int> ............... filter strength (0=off..100), default=60
+ -sharpness <int> ....... filter sharpness (0:most .. 7:least sharp), default=0
+ -strong ................ use strong filter instead of simple (default)
+ -nostrong .............. use simple filter instead of strong
+ -sharp_yuv ............. use sharper (and slower) RGB->YUV conversion
+ -partition_limit <int> . limit quality to fit the 512k limit on
+ the first partition (0=no degradation ... 100=full)
+ -pass <int> ............ analysis pass number (1..10)
+ -crop <x> <y> <w> <h> .. crop picture with the given rectangle
+ -resize <w> <h> ........ resize picture (after any cropping)
+ -mt .................... use multi-threading if available
+ -low_memory ............ reduce memory usage (slower encoding)
+ -map <int> ............. print map of extra info
+ -print_psnr ............ prints averaged PSNR distortion
+ -print_ssim ............ prints averaged SSIM distortion
+ -print_lsim ............ prints local-similarity distortion
+ -d <file.pgm> .......... dump the compressed output (PGM file)
+ -alpha_method <int> .... transparency-compression method (0..1), default=1
+ -alpha_filter <string> . predictive filtering for alpha plane,
+ one of: none, fast (default) or best
+ -exact ................. preserve RGB values in transparent area, default=off
+ -blend_alpha <hex> ..... blend colors against background color
+ expressed as RGB values written in
+ hexadecimal, e.g. 0xc0e0d0 for red=0xc0
+ green=0xe0 and blue=0xd0
+ -noalpha ............... discard any transparency information
+ -lossless .............. encode image losslessly, default=off
+ -near_lossless <int> ... use near-lossless image
+ preprocessing (0..100=off), default=100
+ -hint <string> ......... specify image characteristics hint,
+ one of: photo, picture or graph
+
+ -metadata <string> ..... comma separated list of metadata to
+ copy from the input to the output if present.
+ Valid values: all, none (default), exif, icc, xmp
+
+ -short ................. condense printed message
+ -quiet ................. don't print anything
+ -version ............... print version number and exit
+ -noasm ................. disable all assembly optimizations
+ -v ..................... verbose, e.g. print encoding/decoding times
+ -progress .............. report encoding progress
+
+Experimental Options:
+ -jpeg_like ............. roughly match expected JPEG size
+ -af .................... auto-adjust filter strength
+ -pre <int> ............. pre-processing filter
+
+The main options you might want to try in order to further tune the
+visual quality are:
+ -preset
+ -sns
+ -f
+ -m
+
+Namely:
+ * 'preset' will set up a default encoding configuration targeting a
+ particular type of input. It should appear first in the list of options,
+ so that subsequent options can take effect on top of this preset.
+ Default value is 'default'.
+ * 'sns' will progressively turn on (when going from 0 to 100) some additional
+ visual optimizations (like: segmentation map re-enforcement). This option
+ will balance the bit allocation differently. It tries to take bits from the
+ "easy" parts of the picture and use them in the "difficult" ones instead.
+ Usually, raising the sns value (at fixed -q value) leads to larger files,
+ but with better quality.
+ Typical value is around '75'.
+ * 'f' option directly links to the filtering strength used by the codec's
+ in-loop processing. The higher the value, the smoother the
+ highly-compressed area will look. This is particularly useful when aiming
+ at very small files. Typical values are around 20-30. Note that using the
+ option -strong/-nostrong will change the type of filtering. Use "-f 0" to
+ turn filtering off.
+ * 'm' controls the trade-off between encoding speed and quality. Default is 4.
+ You can try -m 5 or -m 6 to explore more (time-consuming) encoding
+ possibilities. A lower value will result in faster encoding at the expense
+ of quality.
+
+Decoding tool:
+==============
+
+There is a decoding sample in examples/dwebp.c which will take
+a .webp file and decode it to a PNG image file (amongst other formats).
+This is simply to demonstrate the use of the API. You can verify the
+file test.webp decodes to exactly the same as test_ref.ppm by using:
+
+ cd examples
+ ./dwebp test.webp -ppm -o test.ppm
+ diff test.ppm test_ref.ppm
+
+The full list of options is available using -h:
+
+> dwebp -h
+Usage: dwebp in_file [options] [-o out_file]
+
+Decodes the WebP image file to PNG format [Default]
+Use following options to convert into alternate image formats:
+ -pam ......... save the raw RGBA samples as a color PAM
+ -ppm ......... save the raw RGB samples as a color PPM
+ -bmp ......... save as uncompressed BMP format
+ -tiff ........ save as uncompressed TIFF format
+ -pgm ......... save the raw YUV samples as a grayscale PGM
+ file with IMC4 layout
+ -yuv ......... save the raw YUV samples in flat layout
+
+ Other options are:
+ -version ..... print version number and exit
+ -nofancy ..... don't use the fancy YUV420 upscaler
+ -nofilter .... disable in-loop filtering
+ -nodither .... disable dithering
+ -dither <d> .. dithering strength (in 0..100)
+ -alpha_dither use alpha-plane dithering if needed
+ -mt .......... use multi-threading
+ -crop <x> <y> <w> <h> ... crop output with the given rectangle
+ -resize <w> <h> ......... scale the output (*after* any cropping)
+ -flip ........ flip the output vertically
+ -alpha ....... only save the alpha plane
+ -incremental . use incremental decoding (useful for tests)
+ -h ........... this help message
+ -v ........... verbose (e.g. print encoding/decoding times)
+ -quiet ....... quiet mode, don't print anything
+ -noasm ....... disable all assembly optimizations
+
+WebP file analysis tool:
+========================
+
+'webpinfo' can be used to print out the chunk level structure and bitstream
+header information of WebP files. It can also check if the files are of valid
+WebP format.
+
+Usage: webpinfo [options] in_files
+Note: there could be multiple input files;
+ options must come before input files.
+Options:
+ -version ........... Print version number and exit.
+ -quiet ............. Do not show chunk parsing information.
+ -diag .............. Show parsing error diagnosis.
+ -summary ........... Show chunk stats summary.
+ -bitstream_info .... Parse bitstream header.
+
+Visualization tool:
+===================
+
+There's a little self-serve visualization tool called 'vwebp' under the
+examples/ directory. It uses OpenGL to open a simple drawing window and show
+a decoded WebP file. It's not yet integrated in the automake build system, but
+you can try to manually compile it using the recommendations below.
+
+Usage: vwebp in_file [options]
+
+Decodes the WebP image file and visualize it using OpenGL
+Options are:
+ -version ..... print version number and exit
+ -noicc ....... don't use the icc profile if present
+ -nofancy ..... don't use the fancy YUV420 upscaler
+ -nofilter .... disable in-loop filtering
+ -dither <int> dithering strength (0..100), default=50
+ -noalphadither disable alpha plane dithering
+ -usebgcolor .. display background color
+ -mt .......... use multi-threading
+ -info ........ print info
+ -h ........... this help message
+
+Keyboard shortcuts:
+ 'c' ................ toggle use of color profile
+ 'b' ................ toggle background color display
+ 'i' ................ overlay file information
+ 'd' ................ disable blending & disposal (debug)
+ 'q' / 'Q' / ESC .... quit
+
+Building:
+---------
+
+Prerequisites:
+1) OpenGL & OpenGL Utility Toolkit (GLUT)
+ Linux:
+ $ sudo apt-get install freeglut3-dev mesa-common-dev
+ Mac + XCode:
+ - These libraries should be available in the OpenGL / GLUT frameworks.
+ Windows:
+ http://freeglut.sourceforge.net/index.php#download
+
+2) (Optional) qcms (Quick Color Management System)
+ i. Download qcms from Mozilla / Chromium:
+ http://hg.mozilla.org/mozilla-central/file/0e7639e3bdfb/gfx/qcms
+ http://src.chromium.org/viewvc/chrome/trunk/src/third_party/qcms
+ ii. Build and archive the source files as libqcms.a / qcms.lib
+ iii. Update makefile.unix / Makefile.vc
+ a) Define WEBP_HAVE_QCMS
+ b) Update include / library paths to reference the qcms directory.
+
+Build using makefile.unix / Makefile.vc:
+$ make -f makefile.unix examples/vwebp
+> nmake /f Makefile.vc CFG=release-static \
+ ../obj/x64/release-static/bin/vwebp.exe
+
+Animation creation tool:
+========================
+The utility 'img2webp' can turn a sequence of input images (PNG, JPEG, ...)
+into an animated WebP file. It offers fine control over duration, encoding
+modes, etc.
+
+Usage:
+
+ img2webp [file-level options] [image files...] [per-frame options...]
+
+File-level options (only used at the start of compression):
+ -min_size ............ minimize size
+ -loop <int> .......... loop count (default: 0, = infinite loop)
+ -kmax <int> .......... maximum number of frame between key-frames
+ (0=only keyframes)
+ -kmin <int> .......... minimum number of frame between key-frames
+ (0=disable key-frames altogether)
+ -mixed ............... use mixed lossy/lossless automatic mode
+ -v ................... verbose mode
+ -h ................... this help
+ -version ............. print version number and exit
+
+Per-frame options (only used for subsequent images input):
+ -d <int> ............. frame duration in ms (default: 100)
+ -lossless ........... use lossless mode (default)
+ -lossy ... ........... use lossy mode
+ -q <float> ........... quality
+ -m <int> ............. method to use
+
+example: img2webp -loop 2 in0.png -lossy in1.jpg
+ -d 80 in2.tiff -o out.webp
+
+Note: if a single file name is passed as the argument, the arguments will be
+tokenized from this file. The file name must not start with the character '-'.
+
+Animated GIF conversion:
+========================
+Animated GIF files can be converted to WebP files with animation using the
+gif2webp utility available under examples/. The files can then be viewed using
+vwebp.
+
+Usage:
+ gif2webp [options] gif_file -o webp_file
+Options:
+ -h / -help ............. this help
+ -lossy ................. encode image using lossy compression
+ -mixed ................. for each frame in the image, pick lossy
+ or lossless compression heuristically
+ -q <float> ............. quality factor (0:small..100:big)
+ -m <int> ............... compression method (0=fast, 6=slowest)
+ -min_size .............. minimize output size (default:off)
+ lossless compression by default; can be
+ combined with -q, -m, -lossy or -mixed
+ options
+ -kmin <int> ............ min distance between key frames
+ -kmax <int> ............ max distance between key frames
+ -f <int> ............... filter strength (0=off..100)
+ -metadata <string> ..... comma separated list of metadata to
+ copy from the input to the output if present
+ Valid values: all, none, icc, xmp (default)
+ -loop_compatibility .... use compatibility mode for Chrome
+ version prior to M62 (inclusive)
+ -mt .................... use multi-threading if available
+
+ -version ............... print version number and exit
+ -v ..................... verbose
+ -quiet ................. don't print anything
+
+Building:
+---------
+With the libgif development files installed, gif2webp can be built using
+makefile.unix:
+$ make -f makefile.unix examples/gif2webp
+
+or using autoconf:
+$ ./configure --enable-everything
+$ make
+
+Comparison of animated images:
+==============================
+Test utility anim_diff under examples/ can be used to compare two animated
+images (each can be GIF or WebP).
+
+Usage: anim_diff <image1> <image2> [options]
+
+Options:
+ -dump_frames <folder> dump decoded frames in PAM format
+ -min_psnr <float> ... minimum per-frame PSNR
+ -raw_comparison ..... if this flag is not used, RGB is
+ premultiplied before comparison
+ -max_diff <int> ..... maximum allowed difference per channel
+ between corresponding pixels in subsequent
+ frames
+ -h .................. this help
+ -version ............ print version number and exit
+
+Building:
+---------
+With the libgif development files and a C++ compiler installed, anim_diff can
+be built using makefile.unix:
+$ make -f makefile.unix examples/anim_diff
+
+or using autoconf:
+$ ./configure --enable-everything
+$ make
+
+Encoding API:
+=============
+
+The main encoding functions are available in the header src/webp/encode.h
+The ready-to-use ones are:
+size_t WebPEncodeRGB(const uint8_t* rgb, int width, int height, int stride,
+ float quality_factor, uint8_t** output);
+size_t WebPEncodeBGR(const uint8_t* bgr, int width, int height, int stride,
+ float quality_factor, uint8_t** output);
+size_t WebPEncodeRGBA(const uint8_t* rgba, int width, int height, int stride,
+ float quality_factor, uint8_t** output);
+size_t WebPEncodeBGRA(const uint8_t* bgra, int width, int height, int stride,
+ float quality_factor, uint8_t** output);
+
+They will convert raw RGB samples to a WebP data. The only control supplied
+is the quality factor.
+
+There are some variants for using the lossless format:
+
+size_t WebPEncodeLosslessRGB(const uint8_t* rgb, int width, int height,
+ int stride, uint8_t** output);
+size_t WebPEncodeLosslessBGR(const uint8_t* bgr, int width, int height,
+ int stride, uint8_t** output);
+size_t WebPEncodeLosslessRGBA(const uint8_t* rgba, int width, int height,
+ int stride, uint8_t** output);
+size_t WebPEncodeLosslessBGRA(const uint8_t* bgra, int width, int height,
+ int stride, uint8_t** output);
+
+Of course in this case, no quality factor is needed since the compression
+occurs without loss of the input values, at the expense of larger output sizes.
+
+Advanced encoding API:
+----------------------
+
+A more advanced API is based on the WebPConfig and WebPPicture structures.
+
+WebPConfig contains the encoding settings and is not tied to a particular
+picture.
+WebPPicture contains input data, on which some WebPConfig will be used for
+compression.
+The encoding flow looks like:
+
+-------------------------------------- BEGIN PSEUDO EXAMPLE
+
+#include <webp/encode.h>
+
+ // Setup a config, starting form a preset and tuning some additional
+ // parameters
+ WebPConfig config;
+ if (!WebPConfigPreset(&config, WEBP_PRESET_PHOTO, quality_factor)) {
+ return 0; // version error
+ }
+ // ... additional tuning
+ config.sns_strength = 90;
+ config.filter_sharpness = 6;
+ config_error = WebPValidateConfig(&config); // not mandatory, but useful
+
+ // Setup the input data
+ WebPPicture pic;
+ if (!WebPPictureInit(&pic)) {
+ return 0; // version error
+ }
+ pic.width = width;
+ pic.height = height;
+ // allocated picture of dimension width x height
+ if (!WebPPictureAllocate(&pic)) {
+ return 0; // memory error
+ }
+ // at this point, 'pic' has been initialized as a container,
+ // and can receive the Y/U/V samples.
+ // Alternatively, one could use ready-made import functions like
+ // WebPPictureImportRGB(), which will take care of memory allocation.
+ // In any case, past this point, one will have to call
+ // WebPPictureFree(&pic) to reclaim memory.
+
+ // Set up a byte-output write method. WebPMemoryWriter, for instance.
+ WebPMemoryWriter wrt;
+ WebPMemoryWriterInit(&wrt); // initialize 'wrt'
+
+ pic.writer = MyFileWriter;
+ pic.custom_ptr = my_opaque_structure_to_make_MyFileWriter_work;
+
+ // Compress!
+ int ok = WebPEncode(&config, &pic); // ok = 0 => error occurred!
+ WebPPictureFree(&pic); // must be called independently of the 'ok' result.
+
+ // output data should have been handled by the writer at that point.
+ // -> compressed data is the memory buffer described by wrt.mem / wrt.size
+
+ // deallocate the memory used by compressed data
+ WebPMemoryWriterClear(&wrt);
+
+-------------------------------------- END PSEUDO EXAMPLE
+
+Decoding API:
+=============
+
+This is mainly just one function to call:
+
+#include "webp/decode.h"
+uint8_t* WebPDecodeRGB(const uint8_t* data, size_t data_size,
+ int* width, int* height);
+
+Please have a look at the file src/webp/decode.h for the details.
+There are variants for decoding in BGR/RGBA/ARGB/BGRA order, along with
+decoding to raw Y'CbCr samples. One can also decode the image directly into a
+pre-allocated buffer.
+
+To detect a WebP file and gather the picture's dimensions, the function:
+ int WebPGetInfo(const uint8_t* data, size_t data_size,
+ int* width, int* height);
+is supplied. No decoding is involved when using it.
+
+Incremental decoding API:
+=========================
+
+In the case when data is being progressively transmitted, pictures can still
+be incrementally decoded using a slightly more complicated API. Decoder state
+is stored into an instance of the WebPIDecoder object. This object can be
+created with the purpose of decoding either RGB or Y'CbCr samples.
+For instance:
+
+ WebPDecBuffer buffer;
+ WebPInitDecBuffer(&buffer);
+ buffer.colorspace = MODE_BGR;
+ ...
+ WebPIDecoder* idec = WebPINewDecoder(&buffer);
+
+As data is made progressively available, this incremental-decoder object
+can be used to decode the picture further. There are two (mutually exclusive)
+ways to pass freshly arrived data:
+
+either by appending the fresh bytes:
+
+ WebPIAppend(idec, fresh_data, size_of_fresh_data);
+
+or by just mentioning the new size of the transmitted data:
+
+ WebPIUpdate(idec, buffer, size_of_transmitted_buffer);
+
+Note that 'buffer' can be modified between each call to WebPIUpdate, in
+particular when the buffer is resized to accommodate larger data.
+
+These functions will return the decoding status: either VP8_STATUS_SUSPENDED if
+decoding is not finished yet or VP8_STATUS_OK when decoding is done. Any other
+status is an error condition.
+
+The 'idec' object must always be released (even upon an error condition) by
+calling: WebPDelete(idec).
+
+To retrieve partially decoded picture samples, one must use the corresponding
+method: WebPIDecGetRGB or WebPIDecGetYUVA.
+It will return the last displayable pixel row.
+
+Lastly, note that decoding can also be performed into a pre-allocated pixel
+buffer. This buffer must be passed when creating a WebPIDecoder, calling
+WebPINewRGB() or WebPINewYUVA().
+
+Please have a look at the src/webp/decode.h header for further details.
+
+Advanced Decoding API:
+======================
+
+WebP decoding supports an advanced API which provides on-the-fly cropping and
+rescaling, something of great usefulness on memory-constrained environments like
+mobile phones. Basically, the memory usage will scale with the output's size,
+not the input's, when one only needs a quick preview or a zoomed in portion of
+an otherwise too-large picture. Some CPU can be saved too, incidentally.
+
+-------------------------------------- BEGIN PSEUDO EXAMPLE
+ // A) Init a configuration object
+ WebPDecoderConfig config;
+ CHECK(WebPInitDecoderConfig(&config));
+
+ // B) optional: retrieve the bitstream's features.
+ CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK);
+
+ // C) Adjust 'config' options, if needed
+ config.options.no_fancy_upsampling = 1;
+ config.options.use_scaling = 1;
+ config.options.scaled_width = scaledWidth();
+ config.options.scaled_height = scaledHeight();
+ // etc.
+
+ // D) Specify 'config' output options for specifying output colorspace.
+ // Optionally the external image decode buffer can also be specified.
+ config.output.colorspace = MODE_BGRA;
+ // Optionally, the config.output can be pointed to an external buffer as
+ // well for decoding the image. This externally supplied memory buffer
+ // should be big enough to store the decoded picture.
+ config.output.u.RGBA.rgba = (uint8_t*) memory_buffer;
+ config.output.u.RGBA.stride = scanline_stride;
+ config.output.u.RGBA.size = total_size_of_the_memory_buffer;
+ config.output.is_external_memory = 1;
+
+ // E) Decode the WebP image. There are two variants w.r.t decoding image.
+ // The first one (E.1) decodes the full image and the second one (E.2) is
+ // used to incrementally decode the image using small input buffers.
+ // Any one of these steps can be used to decode the WebP image.
+
+ // E.1) Decode full image.
+ CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK);
+
+ // E.2) Decode image incrementally.
+ WebPIDecoder* const idec = WebPIDecode(NULL, NULL, &config);
+ CHECK(idec != NULL);
+ while (bytes_remaining > 0) {
+ VP8StatusCode status = WebPIAppend(idec, input, bytes_read);
+ if (status == VP8_STATUS_OK || status == VP8_STATUS_SUSPENDED) {
+ bytes_remaining -= bytes_read;
+ } else {
+ break;
+ }
+ }
+ WebPIDelete(idec);
+
+ // F) Decoded image is now in config.output (and config.output.u.RGBA).
+ // It can be saved, displayed or otherwise processed.
+
+ // G) Reclaim memory allocated in config's object. It's safe to call
+ // this function even if the memory is external and wasn't allocated
+ // by WebPDecode().
+ WebPFreeDecBuffer(&config.output);
+
+-------------------------------------- END PSEUDO EXAMPLE
+
+Bugs:
+=====
+
+Please report all bugs to the issue tracker:
+ https://bugs.chromium.org/p/webp
+Patches welcome! See this page to get started:
+ http://www.webmproject.org/code/contribute/submitting-patches/
+
+Discuss:
+========
+
+Email: webp-discuss@webmproject.org
+Web: http://groups.google.com/a/webmproject.org/group/webp-discuss
diff --git a/media/libwebp/README.mux b/media/libwebp/README.mux
new file mode 100644
index 0000000000..22560fe8cf
--- /dev/null
+++ b/media/libwebp/README.mux
@@ -0,0 +1,256 @@
+ __ __ ____ ____ ____ __ __ _ __ __
+ / \\/ \/ _ \/ _ \/ _ \/ \ \/ \___/_ / _\
+ \ / __/ _ \ __/ / / (_/ /__
+ \__\__/\_____/_____/__/ \__//_/\_____/__/___/v1.1.0
+
+
+Description:
+============
+
+WebPMux: set of two libraries 'Mux' and 'Demux' for creation, extraction and
+manipulation of an extended format WebP file, which can have features like
+color profile, metadata and animation. Reference command-line tools 'webpmux'
+and 'vwebp' as well as the WebP container specification
+'doc/webp-container-spec.txt' are also provided in this package.
+
+WebP Mux tool:
+==============
+
+The examples/ directory contains a tool (webpmux) for manipulating WebP
+files. The webpmux tool can be used to create an extended format WebP file and
+also to extract or strip relevant data from such a file.
+
+A list of options is available using the -help command line flag:
+
+> webpmux -help
+Usage: webpmux -get GET_OPTIONS INPUT -o OUTPUT
+ webpmux -set SET_OPTIONS INPUT -o OUTPUT
+ webpmux -duration DURATION_OPTIONS [-duration ...]
+ INPUT -o OUTPUT
+ webpmux -strip STRIP_OPTIONS INPUT -o OUTPUT
+ webpmux -frame FRAME_OPTIONS [-frame...] [-loop LOOP_COUNT]
+ [-bgcolor BACKGROUND_COLOR] -o OUTPUT
+ webpmux -info INPUT
+ webpmux [-h|-help]
+ webpmux -version
+ webpmux argument_file_name
+
+GET_OPTIONS:
+ Extract relevant data:
+ icc get ICC profile
+ exif get EXIF metadata
+ xmp get XMP metadata
+ frame n get nth frame
+
+SET_OPTIONS:
+ Set color profile/metadata:
+ icc file.icc set ICC profile
+ exif file.exif set EXIF metadata
+ xmp file.xmp set XMP metadata
+ where: 'file.icc' contains the ICC profile to be set,
+ 'file.exif' contains the EXIF metadata to be set
+ 'file.xmp' contains the XMP metadata to be set
+
+DURATION_OPTIONS:
+ Set duration of selected frames:
+ duration set duration for each frames
+ duration,frame set duration of a particular frame
+ duration,start,end set duration of frames in the
+ interval [start,end])
+ where: 'duration' is the duration in milliseconds
+ 'start' is the start frame index
+ 'end' is the inclusive end frame index
+ The special 'end' value '0' means: last frame.
+
+STRIP_OPTIONS:
+ Strip color profile/metadata:
+ icc strip ICC profile
+ exif strip EXIF metadata
+ xmp strip XMP metadata
+
+FRAME_OPTIONS(i):
+ Create animation:
+ file_i +di+[xi+yi[+mi[bi]]]
+ where: 'file_i' is the i'th animation frame (WebP format),
+ 'di' is the pause duration before next frame,
+ 'xi','yi' specify the image offset for this frame,
+ 'mi' is the dispose method for this frame (0 or 1),
+ 'bi' is the blending method for this frame (+b or -b)
+
+LOOP_COUNT:
+ Number of times to repeat the animation.
+ Valid range is 0 to 65535 [Default: 0 (infinite)].
+
+BACKGROUND_COLOR:
+ Background color of the canvas.
+ A,R,G,B
+ where: 'A', 'R', 'G' and 'B' are integers in the range 0 to 255 specifying
+ the Alpha, Red, Green and Blue component values respectively
+ [Default: 255,255,255,255]
+
+INPUT & OUTPUT are in WebP format.
+
+Note: The nature of EXIF, XMP and ICC data is not checked and is assumed to be
+valid.
+
+Note: if a single file name is passed as the argument, the arguments will be
+tokenized from this file. The file name must not start with the character '-'.
+
+Visualization tool:
+===================
+
+The examples/ directory also contains a tool (vwebp) for viewing WebP files.
+It decodes the image and visualizes it using OpenGL. See the libwebp README
+for details on building and running this program.
+
+Mux API:
+========
+The Mux API contains methods for adding data to and reading data from WebP
+files. This API currently supports XMP/EXIF metadata, ICC profile and animation.
+Other features may be added in subsequent releases.
+
+Example#1 (pseudo code): Creating a WebPMux object with image data, color
+profile and XMP metadata.
+
+ int copy_data = 0;
+ WebPMux* mux = WebPMuxNew();
+ // ... (Prepare image data).
+ WebPMuxSetImage(mux, &image, copy_data);
+ // ... (Prepare ICC profile data).
+ WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data);
+ // ... (Prepare XMP metadata).
+ WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data);
+ // Get data from mux in WebP RIFF format.
+ WebPMuxAssemble(mux, &output_data);
+ WebPMuxDelete(mux);
+ // ... (Consume output_data; e.g. write output_data.bytes to file).
+ WebPDataClear(&output_data);
+
+
+Example#2 (pseudo code): Get image and color profile data from a WebP file.
+
+ int copy_data = 0;
+ // ... (Read data from file).
+ WebPMux* mux = WebPMuxCreate(&data, copy_data);
+ WebPMuxGetFrame(mux, 1, &image);
+ // ... (Consume image; e.g. call WebPDecode() to decode the data).
+ WebPMuxGetChunk(mux, "ICCP", &icc_profile);
+ // ... (Consume icc_profile).
+ WebPMuxDelete(mux);
+ free(data);
+
+
+For a detailed Mux API reference, please refer to the header file
+(src/webp/mux.h).
+
+Demux API:
+==========
+The Demux API enables extraction of images and extended format data from
+WebP files. This API currently supports reading of XMP/EXIF metadata, ICC
+profile and animated images. Other features may be added in subsequent
+releases.
+
+Code example: Demuxing WebP data to extract all the frames, ICC profile
+and EXIF/XMP metadata.
+
+ WebPDemuxer* demux = WebPDemux(&webp_data);
+ uint32_t width = WebPDemuxGetI(demux, WEBP_FF_CANVAS_WIDTH);
+ uint32_t height = WebPDemuxGetI(demux, WEBP_FF_CANVAS_HEIGHT);
+ // ... (Get information about the features present in the WebP file).
+ uint32_t flags = WebPDemuxGetI(demux, WEBP_FF_FORMAT_FLAGS);
+
+ // ... (Iterate over all frames).
+ WebPIterator iter;
+ if (WebPDemuxGetFrame(demux, 1, &iter)) {
+ do {
+ // ... (Consume 'iter'; e.g. Decode 'iter.fragment' with WebPDecode(),
+ // ... and get other frame properties like width, height, offsets etc.
+ // ... see 'struct WebPIterator' below for more info).
+ } while (WebPDemuxNextFrame(&iter));
+ WebPDemuxReleaseIterator(&iter);
+ }
+
+ // ... (Extract metadata).
+ WebPChunkIterator chunk_iter;
+ if (flags & ICCP_FLAG) WebPDemuxGetChunk(demux, "ICCP", 1, &chunk_iter);
+ // ... (Consume the ICC profile in 'chunk_iter.chunk').
+ WebPDemuxReleaseChunkIterator(&chunk_iter);
+ if (flags & EXIF_FLAG) WebPDemuxGetChunk(demux, "EXIF", 1, &chunk_iter);
+ // ... (Consume the EXIF metadata in 'chunk_iter.chunk').
+ WebPDemuxReleaseChunkIterator(&chunk_iter);
+ if (flags & XMP_FLAG) WebPDemuxGetChunk(demux, "XMP ", 1, &chunk_iter);
+ // ... (Consume the XMP metadata in 'chunk_iter.chunk').
+ WebPDemuxReleaseChunkIterator(&chunk_iter);
+ WebPDemuxDelete(demux);
+
+
+For a detailed Demux API reference, please refer to the header file
+(src/webp/demux.h).
+
+AnimEncoder API:
+================
+The AnimEncoder API can be used to create animated WebP images.
+
+Code example:
+
+ WebPAnimEncoderOptions enc_options;
+ WebPAnimEncoderOptionsInit(&enc_options);
+ // ... (Tune 'enc_options' as needed).
+ WebPAnimEncoder* enc = WebPAnimEncoderNew(width, height, &enc_options);
+ while(<there are more frames>) {
+ WebPConfig config;
+ WebPConfigInit(&config);
+ // ... (Tune 'config' as needed).
+ WebPAnimEncoderAdd(enc, frame, duration, &config);
+ }
+ WebPAnimEncoderAssemble(enc, webp_data);
+ WebPAnimEncoderDelete(enc);
+ // ... (Write the 'webp_data' to a file, or re-mux it further).
+
+
+For a detailed AnimEncoder API reference, please refer to the header file
+(src/webp/mux.h).
+
+AnimDecoder API:
+================
+This AnimDecoder API allows decoding (possibly) animated WebP images.
+
+Code Example:
+
+ WebPAnimDecoderOptions dec_options;
+ WebPAnimDecoderOptionsInit(&dec_options);
+ // Tune 'dec_options' as needed.
+ WebPAnimDecoder* dec = WebPAnimDecoderNew(webp_data, &dec_options);
+ WebPAnimInfo anim_info;
+ WebPAnimDecoderGetInfo(dec, &anim_info);
+ for (uint32_t i = 0; i < anim_info.loop_count; ++i) {
+ while (WebPAnimDecoderHasMoreFrames(dec)) {
+ uint8_t* buf;
+ int timestamp;
+ WebPAnimDecoderGetNext(dec, &buf, &timestamp);
+ // ... (Render 'buf' based on 'timestamp').
+ // ... (Do NOT free 'buf', as it is owned by 'dec').
+ }
+ WebPAnimDecoderReset(dec);
+ }
+ const WebPDemuxer* demuxer = WebPAnimDecoderGetDemuxer(dec);
+ // ... (Do something using 'demuxer'; e.g. get EXIF/XMP/ICC data).
+ WebPAnimDecoderDelete(dec);
+
+For a detailed AnimDecoder API reference, please refer to the header file
+(src/webp/demux.h).
+
+
+Bugs:
+=====
+
+Please report all bugs to the issue tracker:
+ https://bugs.chromium.org/p/webp
+Patches welcome! See this page to get started:
+ http://www.webmproject.org/code/contribute/submitting-patches/
+
+Discuss:
+========
+
+Email: webp-discuss@webmproject.org
+Web: http://groups.google.com/a/webmproject.org/group/webp-discuss
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-13 02:45:36 +0000