NameDateSize

..10-Aug-201812 KiB

Android.bp10-Aug-20185.9 KiB

ChangeLog10-Aug-2018890

COPYING10-Aug-20181.5 KiB

include/10-Aug-20184 KiB

MODULE_LICENSE_BSD10-Aug-20180

NOTICE10-Aug-20181.5 KiB

PATENTS10-Aug-20181.4 KiB

README10-Aug-201828.7 KiB

README.android10-Aug-2018739

README.version10-Aug-2018132

src/10-Aug-20184 KiB

README

1          __   __  ____  ____  ____
2         /  \\/  \/  _ \/  _ )/  _ \
3         \       /   __/  _  \   __/
4          \__\__/\____/\_____/__/ ____  ___
5                / _/ /    \    \ /  _ \/ _/
6               /  \_/   / /   \ \   __/  \__
7               \____/____/\_____/_____/____/v0.6.1
8
9Description:
10============
11
12WebP codec: library to encode and decode images in WebP format. This package
13contains the library that can be used in other programs to add WebP support,
14as well as the command line tools 'cwebp' and 'dwebp'.
15
16See http://developers.google.com/speed/webp
17
18The latest source tree is available at
19https://chromium.googlesource.com/webm/libwebp
20
21It is released under the same license as the WebM project.
22See http://www.webmproject.org/license/software/ or the
23"COPYING" file for details. An additional intellectual
24property rights grant can be found in the file PATENTS.
25
26Building:
27=========
28
29Windows build:
30--------------
31
32By running:
33
34  nmake /f Makefile.vc CFG=release-static RTLIBCFG=static OBJDIR=output
35
36the directory output\release-static\(x64|x86)\bin will contain the tools
37cwebp.exe and dwebp.exe. The directory output\release-static\(x64|x86)\lib will
38contain the libwebp static library.
39The target architecture (x86/x64) is detected by Makefile.vc from the Visual
40Studio compiler (cl.exe) available in the system path.
41
42Unix build using makefile.unix:
43-------------------------------
44
45On platforms with GNU tools installed (gcc and make), running
46
47  make -f makefile.unix
48
49will build the binaries examples/cwebp and examples/dwebp, along
50with the static library src/libwebp.a. No system-wide installation
51is supplied, as this is a simple alternative to the full installation
52system based on the autoconf tools (see below).
53Please refer to makefile.unix for additional details and customizations.
54
55Using autoconf tools:
56---------------------
57Prerequisites:
58A compiler (e.g., gcc), make, autoconf, automake, libtool.
59On a Debian-like system the following should install everything you need for a
60minimal build:
61$ sudo apt-get install gcc make autoconf automake libtool
62
63When building from git sources, you will need to run autogen.sh to generate the
64configure script.
65
66./configure
67make
68make install
69
70should be all you need to have the following files
71
72/usr/local/include/webp/decode.h
73/usr/local/include/webp/encode.h
74/usr/local/include/webp/types.h
75/usr/local/lib/libwebp.*
76/usr/local/bin/cwebp
77/usr/local/bin/dwebp
78
79installed.
80
81Note: A decode-only library, libwebpdecoder, is available using the
82'--enable-libwebpdecoder' flag. The encode library is built separately and can
83be installed independently using a minor modification in the corresponding
84Makefile.am configure files (see comments there). See './configure --help' for
85more options.
86
87Building for MIPS Linux:
88------------------------
89MIPS Linux toolchain stable available releases can be found at:
90https://community.imgtec.com/developers/mips/tools/codescape-mips-sdk/available-releases/
91
92# Add toolchain to PATH
93export PATH=$PATH:/path/to/toolchain/bin
94
95# 32-bit build for mips32r5 (p5600)
96HOST=mips-mti-linux-gnu
97MIPS_CFLAGS="-O3 -mips32r5 -mabi=32 -mtune=p5600 -mmsa -mfp64 \
98  -msched-weight -mload-store-pairs -fPIE"
99MIPS_LDFLAGS="-mips32r5 -mabi=32 -mmsa -mfp64 -pie"
100
101# 64-bit build for mips64r6 (i6400)
102HOST=mips-img-linux-gnu
103MIPS_CFLAGS="-O3 -mips64r6 -mabi=64 -mtune=i6400 -mmsa -mfp64 \
104  -msched-weight -mload-store-pairs -fPIE"
105MIPS_LDFLAGS="-mips64r6 -mabi=64 -mmsa -mfp64 -pie"
106
107./configure --host=${HOST} --build=`config.guess` \
108  CC="${HOST}-gcc -EL" \
109  CFLAGS="$MIPS_CFLAGS" \
110  LDFLAGS="$MIPS_LDFLAGS"
111make
112make install
113
114CMake:
115------
116With CMake, you can compile libwebp, cwebp, dwebp, gif2web, img2webp, webpinfo
117and the JS bindings.
118
119Prerequisites:
120A compiler (e.g., gcc with autotools) and CMake.
121On a Debian-like system the following should install everything you need for a
122minimal build:
123$ sudo apt-get install build-essential cmake
124
125When building from git sources, you will need to run cmake to generate the
126makefiles.
127
128mkdir build && cd build && cmake ../
129make
130make install
131
132If you also want any of the executables, you will need to enable them through
133CMake, e.g.:
134
135cmake -DWEBP_BUILD_CWEBP=ON -DWEBP_BUILD_DWEBP=ON ../
136
137or through your favorite interface (like ccmake or cmake-qt-gui).
138
139Finally, once installed, you can also use WebP in your CMake project by doing:
140
141find_package(WebP)
142
143which will define the CMake variables WebP_INCLUDE_DIRS and WebP_LIBRARIES.
144
145Gradle:
146-------
147The support for Gradle is minimal: it only helps you compile libwebp, cwebp and
148dwebp and webpmux_example.
149
150Prerequisites:
151A compiler (e.g., gcc with autotools) and gradle.
152On a Debian-like system the following should install everything you need for a
153minimal build:
154$ sudo apt-get install build-essential gradle
155
156When building from git sources, you will need to run the Gradle wrapper with the
157appropriate target, e.g. :
158
159./gradlew buildAllExecutables
160
161SWIG bindings:
162--------------
163
164To generate language bindings from swig/libwebp.swig at least swig-1.3
165(http://www.swig.org) is required.
166
167Currently the following functions are mapped:
168Decode:
169  WebPGetDecoderVersion
170  WebPGetInfo
171  WebPDecodeRGBA
172  WebPDecodeARGB
173  WebPDecodeBGRA
174  WebPDecodeBGR
175  WebPDecodeRGB
176
177Encode:
178  WebPGetEncoderVersion
179  WebPEncodeRGBA
180  WebPEncodeBGRA
181  WebPEncodeRGB
182  WebPEncodeBGR
183  WebPEncodeLosslessRGBA
184  WebPEncodeLosslessBGRA
185  WebPEncodeLosslessRGB
186  WebPEncodeLosslessBGR
187
188See swig/README for more detailed build instructions.
189
190Java bindings:
191
192To build the swig-generated JNI wrapper code at least JDK-1.5 (or equivalent)
193is necessary for enum support. The output is intended to be a shared object /
194DLL that can be loaded via System.loadLibrary("webp_jni").
195
196Python bindings:
197
198To build the swig-generated Python extension code at least Python 2.6 is
199required. Python < 2.6 may build with some minor changes to libwebp.swig or the
200generated code, but is untested.
201
202Encoding tool:
203==============
204
205The examples/ directory contains tools for encoding (cwebp) and
206decoding (dwebp) images.
207
208The easiest use should look like:
209  cwebp input.png -q 80 -o output.webp
210which will convert the input file to a WebP file using a quality factor of 80
211on a 0->100 scale (0 being the lowest quality, 100 being the best. Default
212value is 75).
213You might want to try the -lossless flag too, which will compress the source
214(in RGBA format) without any loss. The -q quality parameter will in this case
215control the amount of processing time spent trying to make the output file as
216small as possible.
217
218A longer list of options is available using the -longhelp command line flag:
219
220> cwebp -longhelp
221Usage:
222 cwebp [-preset <...>] [options] in_file [-o out_file]
223
224If input size (-s) for an image is not specified, it is
225assumed to be a PNG, JPEG, TIFF or WebP file.
226
227Options:
228  -h / -help ............. short help
229  -H / -longhelp ......... long help
230  -q <float> ............. quality factor (0:small..100:big), default=75
231  -alpha_q <int> ......... transparency-compression quality (0..100),
232                           default=100
233  -preset <string> ....... preset setting, one of:
234                            default, photo, picture,
235                            drawing, icon, text
236     -preset must come first, as it overwrites other parameters
237  -z <int> ............... activates lossless preset with given
238                           level in [0:fast, ..., 9:slowest]
239
240  -m <int> ............... compression method (0=fast, 6=slowest), default=4
241  -segments <int> ........ number of segments to use (1..4), default=4
242  -size <int> ............ target size (in bytes)
243  -psnr <float> .......... target PSNR (in dB. typically: 42)
244
245  -s <int> <int> ......... input size (width x height) for YUV
246  -sns <int> ............. spatial noise shaping (0:off, 100:max), default=50
247  -f <int> ............... filter strength (0=off..100), default=60
248  -sharpness <int> ....... filter sharpness (0:most .. 7:least sharp), default=0
249  -strong ................ use strong filter instead of simple (default)
250  -nostrong .............. use simple filter instead of strong
251  -sharp_yuv ............. use sharper (and slower) RGB->YUV conversion
252  -partition_limit <int> . limit quality to fit the 512k limit on
253                           the first partition (0=no degradation ... 100=full)
254  -pass <int> ............ analysis pass number (1..10)
255  -crop <x> <y> <w> <h> .. crop picture with the given rectangle
256  -resize <w> <h> ........ resize picture (after any cropping)
257  -mt .................... use multi-threading if available
258  -low_memory ............ reduce memory usage (slower encoding)
259  -map <int> ............. print map of extra info
260  -print_psnr ............ prints averaged PSNR distortion
261  -print_ssim ............ prints averaged SSIM distortion
262  -print_lsim ............ prints local-similarity distortion
263  -d <file.pgm> .......... dump the compressed output (PGM file)
264  -alpha_method <int> .... transparency-compression method (0..1), default=1
265  -alpha_filter <string> . predictive filtering for alpha plane,
266                           one of: none, fast (default) or best
267  -exact ................. preserve RGB values in transparent area, default=off
268  -blend_alpha <hex> ..... blend colors against background color
269                           expressed as RGB values written in
270                           hexadecimal, e.g. 0xc0e0d0 for red=0xc0
271                           green=0xe0 and blue=0xd0
272  -noalpha ............... discard any transparency information
273  -lossless .............. encode image losslessly, default=off
274  -near_lossless <int> ... use near-lossless image
275                           preprocessing (0..100=off), default=100
276  -hint <string> ......... specify image characteristics hint,
277                           one of: photo, picture or graph
278
279  -metadata <string> ..... comma separated list of metadata to
280                           copy from the input to the output if present.
281                           Valid values: all, none (default), exif, icc, xmp
282
283  -short ................. condense printed message
284  -quiet ................. don't print anything
285  -version ............... print version number and exit
286  -noasm ................. disable all assembly optimizations
287  -v ..................... verbose, e.g. print encoding/decoding times
288  -progress .............. report encoding progress
289
290Experimental Options:
291  -jpeg_like ............. roughly match expected JPEG size
292  -af .................... auto-adjust filter strength
293  -pre <int> ............. pre-processing filter
294
295The main options you might want to try in order to further tune the
296visual quality are:
297 -preset
298 -sns
299 -f
300 -m
301
302Namely:
303  * 'preset' will set up a default encoding configuration targeting a
304     particular type of input. It should appear first in the list of options,
305     so that subsequent options can take effect on top of this preset.
306     Default value is 'default'.
307  * 'sns' will progressively turn on (when going from 0 to 100) some additional
308     visual optimizations (like: segmentation map re-enforcement). This option
309     will balance the bit allocation differently. It tries to take bits from the
310     "easy" parts of the picture and use them in the "difficult" ones instead.
311     Usually, raising the sns value (at fixed -q value) leads to larger files,
312     but with better quality.
313     Typical value is around '75'.
314  * 'f' option directly links to the filtering strength used by the codec's
315     in-loop processing. The higher the value, the smoother the
316     highly-compressed area will look. This is particularly useful when aiming
317     at very small files. Typical values are around 20-30. Note that using the
318     option -strong/-nostrong will change the type of filtering. Use "-f 0" to
319     turn filtering off.
320  * 'm' controls the trade-off between encoding speed and quality. Default is 4.
321     You can try -m 5 or -m 6 to explore more (time-consuming) encoding
322     possibilities. A lower value will result in faster encoding at the expense
323     of quality.
324
325Decoding tool:
326==============
327
328There is a decoding sample in examples/dwebp.c which will take
329a .webp file and decode it to a PNG image file (amongst other formats).
330This is simply to demonstrate the use of the API. You can verify the
331file test.webp decodes to exactly the same as test_ref.ppm by using:
332
333 cd examples
334 ./dwebp test.webp -ppm -o test.ppm
335 diff test.ppm test_ref.ppm
336
337The full list of options is available using -h:
338
339> dwebp -h
340Usage: dwebp in_file [options] [-o out_file]
341
342Decodes the WebP image file to PNG format [Default]
343Use following options to convert into alternate image formats:
344  -pam ......... save the raw RGBA samples as a color PAM
345  -ppm ......... save the raw RGB samples as a color PPM
346  -bmp ......... save as uncompressed BMP format
347  -tiff ........ save as uncompressed TIFF format
348  -pgm ......... save the raw YUV samples as a grayscale PGM
349                 file with IMC4 layout
350  -yuv ......... save the raw YUV samples in flat layout
351
352 Other options are:
353  -version ..... print version number and exit
354  -nofancy ..... don't use the fancy YUV420 upscaler
355  -nofilter .... disable in-loop filtering
356  -nodither .... disable dithering
357  -dither <d> .. dithering strength (in 0..100)
358  -alpha_dither  use alpha-plane dithering if needed
359  -mt .......... use multi-threading
360  -crop <x> <y> <w> <h> ... crop output with the given rectangle
361  -resize <w> <h> ......... scale the output (*after* any cropping)
362  -flip ........ flip the output vertically
363  -alpha ....... only save the alpha plane
364  -incremental . use incremental decoding (useful for tests)
365  -h ........... this help message
366  -v ........... verbose (e.g. print encoding/decoding times)
367  -quiet ....... quiet mode, don't print anything
368  -noasm ....... disable all assembly optimizations
369
370WebP file analysis tool:
371========================
372
373'webpinfo' can be used to print out the chunk level structure and bitstream
374header information of WebP files. It can also check if the files are of valid
375WebP format.
376
377Usage: webpinfo [options] in_files
378Note: there could be multiple input files;
379      options must come before input files.
380Options:
381  -version ........... Print version number and exit.
382  -quiet ............. Do not show chunk parsing information.
383  -diag .............. Show parsing error diagnosis.
384  -summary ........... Show chunk stats summary.
385  -bitstream_info .... Parse bitstream header.
386
387Visualization tool:
388===================
389
390There's a little self-serve visualization tool called 'vwebp' under the
391examples/ directory. It uses OpenGL to open a simple drawing window and show
392a decoded WebP file. It's not yet integrated in the automake build system, but
393you can try to manually compile it using the recommendations below.
394
395Usage: vwebp in_file [options]
396
397Decodes the WebP image file and visualize it using OpenGL
398Options are:
399  -version ..... print version number and exit
400  -noicc ....... don't use the icc profile if present
401  -nofancy ..... don't use the fancy YUV420 upscaler
402  -nofilter .... disable in-loop filtering
403  -dither <int>  dithering strength (0..100), default=50
404  -noalphadither disable alpha plane dithering
405  -mt .......... use multi-threading
406  -info ........ print info
407  -h ........... this help message
408
409Keyboard shortcuts:
410  'c' ................ toggle use of color profile
411  'i' ................ overlay file information
412  'd' ................ disable blending & disposal (debug)
413  'q' / 'Q' / ESC .... quit
414
415Building:
416---------
417
418Prerequisites:
4191) OpenGL & OpenGL Utility Toolkit (GLUT)
420  Linux:
421    $ sudo apt-get install freeglut3-dev mesa-common-dev
422  Mac + XCode:
423    - These libraries should be available in the OpenGL / GLUT frameworks.
424  Windows:
425    http://freeglut.sourceforge.net/index.php#download
426
4272) (Optional) qcms (Quick Color Management System)
428  i. Download qcms from Mozilla / Chromium:
429    http://hg.mozilla.org/mozilla-central/file/0e7639e3bdfb/gfx/qcms
430    http://src.chromium.org/viewvc/chrome/trunk/src/third_party/qcms
431  ii. Build and archive the source files as libqcms.a / qcms.lib
432  iii. Update makefile.unix / Makefile.vc
433    a) Define WEBP_HAVE_QCMS
434    b) Update include / library paths to reference the qcms directory.
435
436Build using makefile.unix / Makefile.vc:
437$ make -f makefile.unix examples/vwebp
438> nmake /f Makefile.vc CFG=release-static \
439    ../obj/x64/release-static/bin/vwebp.exe
440
441Animation creation tool:
442========================
443The utility 'img2webp' can turn a sequence of input images (PNG, JPEG, ...)
444into an animated WebP file. It offers fine control over duration, encoding
445modes, etc.
446
447Usage:
448
449  img2webp [file-level options] [image files...] [per-frame options...]
450
451File-level options (only used at the start of compression):
452 -min_size ............ minimize size
453 -loop <int> .......... loop count (default: 0, = infinite loop)
454 -kmax <int> .......... maximum number of frame between key-frames
455                        (0=only keyframes)
456 -kmin <int> .......... minimum number of frame between key-frames
457                        (0=disable key-frames altogether)
458 -mixed ............... use mixed lossy/lossless automatic mode
459 -v ................... verbose mode
460 -h ................... this help
461
462Per-frame options (only used for subsequent images input):
463 -d <int> ............. frame duration in ms (default: 100)
464 -lossless  ........... use lossless mode (default)
465 -lossy ... ........... use lossy mode
466 -q <float> ........... quality
467 -m <int> ............. method to use
468
469example: img2webp -loop 2 in0.png -lossy in1.jpg
470                  -d 80 in2.tiff -o out.webp
471
472Animated GIF conversion:
473========================
474Animated GIF files can be converted to WebP files with animation using the
475gif2webp utility available under examples/. The files can then be viewed using
476vwebp.
477
478Usage:
479 gif2webp [options] gif_file -o webp_file
480Options:
481  -h / -help ............. this help
482  -lossy ................. encode image using lossy compression
483  -mixed ................. for each frame in the image, pick lossy
484                           or lossless compression heuristically
485  -q <float> ............. quality factor (0:small..100:big)
486  -m <int> ............... compression method (0=fast, 6=slowest)
487  -min_size .............. minimize output size (default:off)
488                           lossless compression by default; can be
489                           combined with -q, -m, -lossy or -mixed
490                           options
491  -kmin <int> ............ min distance between key frames
492  -kmax <int> ............ max distance between key frames
493  -f <int> ............... filter strength (0=off..100)
494  -metadata <string> ..... comma separated list of metadata to
495                           copy from the input to the output if present
496                           Valid values: all, none, icc, xmp (default)
497  -loop_compatibility .... use compatibility mode for Chrome
498                           version prior to M62 (inclusive)
499  -mt .................... use multi-threading if available
500
501  -version ............... print version number and exit
502  -v ..................... verbose
503  -quiet ................. don't print anything
504
505Building:
506---------
507With the libgif development files installed, gif2webp can be built using
508makefile.unix:
509$ make -f makefile.unix examples/gif2webp
510
511or using autoconf:
512$ ./configure --enable-everything
513$ make
514
515Comparison of animated images:
516==============================
517Test utility anim_diff under examples/ can be used to compare two animated
518images (each can be GIF or WebP).
519
520Usage: anim_diff <image1> <image2> [options]
521
522Options:
523  -dump_frames <folder> dump decoded frames in PAM format
524  -min_psnr <float> ... minimum per-frame PSNR
525  -raw_comparison ..... if this flag is not used, RGB is
526                        premultiplied before comparison
527
528Building:
529---------
530With the libgif development files and a C++ compiler installed, anim_diff can
531be built using makefile.unix:
532$ make -f makefile.unix examples/anim_diff
533
534or using autoconf:
535$ ./configure --enable-everything
536$ make
537
538Encoding API:
539=============
540
541The main encoding functions are available in the header src/webp/encode.h
542The ready-to-use ones are:
543size_t WebPEncodeRGB(const uint8_t* rgb, int width, int height, int stride,
544                     float quality_factor, uint8_t** output);
545size_t WebPEncodeBGR(const uint8_t* bgr, int width, int height, int stride,
546                     float quality_factor, uint8_t** output);
547size_t WebPEncodeRGBA(const uint8_t* rgba, int width, int height, int stride,
548                      float quality_factor, uint8_t** output);
549size_t WebPEncodeBGRA(const uint8_t* bgra, int width, int height, int stride,
550                      float quality_factor, uint8_t** output);
551
552They will convert raw RGB samples to a WebP data. The only control supplied
553is the quality factor.
554
555There are some variants for using the lossless format:
556
557size_t WebPEncodeLosslessRGB(const uint8_t* rgb, int width, int height,
558                             int stride, uint8_t** output);
559size_t WebPEncodeLosslessBGR(const uint8_t* bgr, int width, int height,
560                             int stride, uint8_t** output);
561size_t WebPEncodeLosslessRGBA(const uint8_t* rgba, int width, int height,
562                              int stride, uint8_t** output);
563size_t WebPEncodeLosslessBGRA(const uint8_t* bgra, int width, int height,
564                              int stride, uint8_t** output);
565
566Of course in this case, no quality factor is needed since the compression
567occurs without loss of the input values, at the expense of larger output sizes.
568
569Advanced encoding API:
570----------------------
571
572A more advanced API is based on the WebPConfig and WebPPicture structures.
573
574WebPConfig contains the encoding settings and is not tied to a particular
575picture.
576WebPPicture contains input data, on which some WebPConfig will be used for
577compression.
578The encoding flow looks like:
579
580-------------------------------------- BEGIN PSEUDO EXAMPLE
581
582#include <webp/encode.h>
583
584  // Setup a config, starting form a preset and tuning some additional
585  // parameters
586  WebPConfig config;
587  if (!WebPConfigPreset(&config, WEBP_PRESET_PHOTO, quality_factor))
588    return 0;   // version error
589  }
590  // ... additional tuning
591  config.sns_strength = 90;
592  config.filter_sharpness = 6;
593  config_error = WebPValidateConfig(&config);  // not mandatory, but useful
594
595  // Setup the input data
596  WebPPicture pic;
597  if (!WebPPictureInit(&pic)) {
598    return 0;  // version error
599  }
600  pic.width = width;
601  pic.height = height;
602  // allocated picture of dimension width x height
603  if (!WebPPictureAllocate(&pic)) {
604    return 0;   // memory error
605  }
606  // at this point, 'pic' has been initialized as a container,
607  // and can receive the Y/U/V samples.
608  // Alternatively, one could use ready-made import functions like
609  // WebPPictureImportRGB(), which will take care of memory allocation.
610  // In any case, past this point, one will have to call
611  // WebPPictureFree(&pic) to reclaim memory.
612
613  // Set up a byte-output write method. WebPMemoryWriter, for instance.
614  WebPMemoryWriter wrt;
615  WebPMemoryWriterInit(&wrt);     // initialize 'wrt'
616
617  pic.writer = MyFileWriter;
618  pic.custom_ptr = my_opaque_structure_to_make_MyFileWriter_work;
619
620  // Compress!
621  int ok = WebPEncode(&config, &pic);   // ok = 0 => error occurred!
622  WebPPictureFree(&pic);  // must be called independently of the 'ok' result.
623
624  // output data should have been handled by the writer at that point.
625  // -> compressed data is the memory buffer described by wrt.mem / wrt.size
626
627  // deallocate the memory used by compressed data
628  WebPMemoryWriterClear(&wrt);
629
630-------------------------------------- END PSEUDO EXAMPLE
631
632Decoding API:
633=============
634
635This is mainly just one function to call:
636
637#include "webp/decode.h"
638uint8_t* WebPDecodeRGB(const uint8_t* data, size_t data_size,
639                       int* width, int* height);
640
641Please have a look at the file src/webp/decode.h for the details.
642There are variants for decoding in BGR/RGBA/ARGB/BGRA order, along with
643decoding to raw Y'CbCr samples. One can also decode the image directly into a
644pre-allocated buffer.
645
646To detect a WebP file and gather the picture's dimensions, the function:
647  int WebPGetInfo(const uint8_t* data, size_t data_size,
648                  int* width, int* height);
649is supplied. No decoding is involved when using it.
650
651Incremental decoding API:
652=========================
653
654In the case when data is being progressively transmitted, pictures can still
655be incrementally decoded using a slightly more complicated API. Decoder state
656is stored into an instance of the WebPIDecoder object. This object can be
657created with the purpose of decoding either RGB or Y'CbCr samples.
658For instance:
659
660  WebPDecBuffer buffer;
661  WebPInitDecBuffer(&buffer);
662  buffer.colorspace = MODE_BGR;
663  ...
664  WebPIDecoder* idec = WebPINewDecoder(&buffer);
665
666As data is made progressively available, this incremental-decoder object
667can be used to decode the picture further. There are two (mutually exclusive)
668ways to pass freshly arrived data:
669
670either by appending the fresh bytes:
671
672  WebPIAppend(idec, fresh_data, size_of_fresh_data);
673
674or by just mentioning the new size of the transmitted data:
675
676  WebPIUpdate(idec, buffer, size_of_transmitted_buffer);
677
678Note that 'buffer' can be modified between each call to WebPIUpdate, in
679particular when the buffer is resized to accommodate larger data.
680
681These functions will return the decoding status: either VP8_STATUS_SUSPENDED if
682decoding is not finished yet or VP8_STATUS_OK when decoding is done. Any other
683status is an error condition.
684
685The 'idec' object must always be released (even upon an error condition) by
686calling: WebPDelete(idec).
687
688To retrieve partially decoded picture samples, one must use the corresponding
689method: WebPIDecGetRGB or WebPIDecGetYUVA.
690It will return the last displayable pixel row.
691
692Lastly, note that decoding can also be performed into a pre-allocated pixel
693buffer. This buffer must be passed when creating a WebPIDecoder, calling
694WebPINewRGB() or WebPINewYUVA().
695
696Please have a look at the src/webp/decode.h header for further details.
697
698Advanced Decoding API:
699======================
700
701WebP decoding supports an advanced API which provides on-the-fly cropping and
702rescaling, something of great usefulness on memory-constrained environments like
703mobile phones. Basically, the memory usage will scale with the output's size,
704not the input's, when one only needs a quick preview or a zoomed in portion of
705an otherwise too-large picture. Some CPU can be saved too, incidentally.
706
707-------------------------------------- BEGIN PSEUDO EXAMPLE
708     // A) Init a configuration object
709     WebPDecoderConfig config;
710     CHECK(WebPInitDecoderConfig(&config));
711
712     // B) optional: retrieve the bitstream's features.
713     CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK);
714
715     // C) Adjust 'config' options, if needed
716     config.options.no_fancy_upsampling = 1;
717     config.options.use_scaling = 1;
718     config.options.scaled_width = scaledWidth();
719     config.options.scaled_height = scaledHeight();
720     // etc.
721
722     // D) Specify 'config' output options for specifying output colorspace.
723     // Optionally the external image decode buffer can also be specified.
724     config.output.colorspace = MODE_BGRA;
725     // Optionally, the config.output can be pointed to an external buffer as
726     // well for decoding the image. This externally supplied memory buffer
727     // should be big enough to store the decoded picture.
728     config.output.u.RGBA.rgba = (uint8_t*) memory_buffer;
729     config.output.u.RGBA.stride = scanline_stride;
730     config.output.u.RGBA.size = total_size_of_the_memory_buffer;
731     config.output.is_external_memory = 1;
732
733     // E) Decode the WebP image. There are two variants w.r.t decoding image.
734     // The first one (E.1) decodes the full image and the second one (E.2) is
735     // used to incrementally decode the image using small input buffers.
736     // Any one of these steps can be used to decode the WebP image.
737
738     // E.1) Decode full image.
739     CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK);
740
741     // E.2) Decode image incrementally.
742     WebPIDecoder* const idec = WebPIDecode(NULL, NULL, &config);
743     CHECK(idec != NULL);
744     while (bytes_remaining > 0) {
745       VP8StatusCode status = WebPIAppend(idec, input, bytes_read);
746       if (status == VP8_STATUS_OK || status == VP8_STATUS_SUSPENDED) {
747         bytes_remaining -= bytes_read;
748       } else {
749         break;
750       }
751     }
752     WebPIDelete(idec);
753
754     // F) Decoded image is now in config.output (and config.output.u.RGBA).
755     // It can be saved, displayed or otherwise processed.
756
757     // G) Reclaim memory allocated in config's object. It's safe to call
758     // this function even if the memory is external and wasn't allocated
759     // by WebPDecode().
760     WebPFreeDecBuffer(&config.output);
761
762-------------------------------------- END PSEUDO EXAMPLE
763
764Bugs:
765=====
766
767Please report all bugs to the issue tracker:
768    https://bugs.chromium.org/p/webp
769Patches welcome! See this page to get started:
770    http://www.webmproject.org/code/contribute/submitting-patches/
771
772Discuss:
773========
774
775Email: webp-discuss@webmproject.org
776Web: http://groups.google.com/a/webmproject.org/group/webp-discuss
777

README.android

1URL: https://chromium.googlesource.com/webm/libwebp
2Version: v0.6.1
3License: Google BSD like
4
5Local modifications:
6- Copy public headers from src/webp to include/webp, so path to headers
7  may be appended into CFLAGS without risk for other private headers
8  (e.g. bits.h) to leak into
9- Removed build files necessary for building via autoconf/automake tools
10  These files are not required to build via Android.bp
11- Undefine WEBP_ANDROID_NEON on Android targets and use __ARM_NEON__
12  instead.
13- cherry-pick 7038ca8d demux,StoreFrame: restore hdr size check to min req
14
15The Android.bp file creates WebP decoder and encoder static libraries which
16can be added to any application by adding libwebp-decode and libwebp-encode to
17'static_libs'.
18

README.version