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