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