• Home
Name Date Size #Lines LOC

..--

fuzz_seed_corpus/03-May-2024-

include/webp/03-May-2024-2,260816

src/03-May-2024-67,88451,581

tests/03-May-2024-7,0326,663

Android.bpD03-May-20248.2 KiB342299

COPYINGD03-May-20241.5 KiB3124

METADATAD03-May-202439 43

MODULE_LICENSE_BSDD03-May-20240

NOTICED03-May-20241.5 KiB3124

OWNERSD03-May-2024256 87

PATENTSD03-May-20241.4 KiB2421

READMED03-May-202429.5 KiB796639

README.androidD03-May-2024584 1512

README.versionD03-May-2024111 43

README

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

README.android

1URL: https://chromium.googlesource.com/webm/libwebp
2Version: v1.2.0
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
12The Android.bp file creates WebP decoder and encoder static libraries which
13can be added to any application by adding libwebp-decode and libwebp-encode to
14'static_libs'.
15

README.version

1URL: https://chromium.googlesource.com/webm/libwebp/+archive/v1.2.0.tar.gz
2Version: v1.2.0
3BugComponent: 20174
4