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