summaryrefslogtreecommitdiff
path: root/media/libwebp/README
blob: 502a4c1c20b822616bbca5c5b81b6848d0b9e669 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
          __   __  ____  ____  ____
         /  \\/  \/  _ \/  _ )/  _ \
         \       /   __/  _  \   __/
          \__\__/\____/\_____/__/ ____  ___
                / _/ /    \    \ /  _ \/ _/
               /  \_/   / /   \ \   __/  \__
               \____/____/\_____/_____/____/v1.0.2

Description:
============

WebP codec: library to encode and decode images in WebP format. This package
contains the library that can be used in other programs to add WebP support,
as well as the command line tools 'cwebp' and 'dwebp'.

See http://developers.google.com/speed/webp

The latest source tree is available at
https://chromium.googlesource.com/webm/libwebp

It is released under the same license as the WebM project.
See http://www.webmproject.org/license/software/ or the
"COPYING" file for details. An additional intellectual
property rights grant can be found in the file PATENTS.

Building:
=========

Windows build:
--------------

By running:

  nmake /f Makefile.vc CFG=release-static RTLIBCFG=static OBJDIR=output

the directory output\release-static\(x64|x86)\bin will contain the tools
cwebp.exe and dwebp.exe. The directory output\release-static\(x64|x86)\lib will
contain the libwebp static library.
The target architecture (x86/x64) is detected by Makefile.vc from the Visual
Studio compiler (cl.exe) available in the system path.

Unix build using makefile.unix:
-------------------------------

On platforms with GNU tools installed (gcc and make), running

  make -f makefile.unix

will build the binaries examples/cwebp and examples/dwebp, along
with the static library src/libwebp.a. No system-wide installation
is supplied, as this is a simple alternative to the full installation
system based on the autoconf tools (see below).
Please refer to makefile.unix for additional details and customizations.

Using autoconf tools:
---------------------
Prerequisites:
A compiler (e.g., gcc), make, autoconf, automake, libtool.
On a Debian-like system the following should install everything you need for a
minimal build:
$ sudo apt-get install gcc make autoconf automake libtool

When building from git sources, you will need to run autogen.sh to generate the
configure script.

./configure
make
make install

should be all you need to have the following files

/usr/local/include/webp/decode.h
/usr/local/include/webp/encode.h
/usr/local/include/webp/types.h
/usr/local/lib/libwebp.*
/usr/local/bin/cwebp
/usr/local/bin/dwebp

installed.

Note: A decode-only library, libwebpdecoder, is available using the
'--enable-libwebpdecoder' flag. The encode library is built separately and can
be installed independently using a minor modification in the corresponding
Makefile.am configure files (see comments there). See './configure --help' for
more options.

Building for MIPS Linux:
------------------------
MIPS Linux toolchain stable available releases can be found at:
https://community.imgtec.com/developers/mips/tools/codescape-mips-sdk/available-releases/

# Add toolchain to PATH
export PATH=$PATH:/path/to/toolchain/bin

# 32-bit build for mips32r5 (p5600)
HOST=mips-mti-linux-gnu
MIPS_CFLAGS="-O3 -mips32r5 -mabi=32 -mtune=p5600 -mmsa -mfp64 \
  -msched-weight -mload-store-pairs -fPIE"
MIPS_LDFLAGS="-mips32r5 -mabi=32 -mmsa -mfp64 -pie"

# 64-bit build for mips64r6 (i6400)
HOST=mips-img-linux-gnu
MIPS_CFLAGS="-O3 -mips64r6 -mabi=64 -mtune=i6400 -mmsa -mfp64 \
  -msched-weight -mload-store-pairs -fPIE"
MIPS_LDFLAGS="-mips64r6 -mabi=64 -mmsa -mfp64 -pie"

./configure --host=${HOST} --build=`config.guess` \
  CC="${HOST}-gcc -EL" \
  CFLAGS="$MIPS_CFLAGS" \
  LDFLAGS="$MIPS_LDFLAGS"
make
make install

CMake:
------
With CMake, you can compile libwebp, cwebp, dwebp, gif2web, img2webp, webpinfo
and the JS bindings.

Prerequisites:
A compiler (e.g., gcc with autotools) and CMake.
On a Debian-like system the following should install everything you need for a
minimal build:
$ sudo apt-get install build-essential cmake

When building from git sources, you will need to run cmake to generate the
makefiles.

mkdir build && cd build && cmake ../
make
make install

If you also want any of the executables, you will need to enable them through
CMake, e.g.:

cmake -DWEBP_BUILD_CWEBP=ON -DWEBP_BUILD_DWEBP=ON ../

or through your favorite interface (like ccmake or cmake-qt-gui).

Use option -DWEBP_UNICODE=ON for Unicode support on Windows (with chcp 65001).

Finally, once installed, you can also use WebP in your CMake project by doing:

find_package(WebP)

which will define the CMake variables WebP_INCLUDE_DIRS and WebP_LIBRARIES.

Gradle:
-------
The support for Gradle is minimal: it only helps you compile libwebp, cwebp and
dwebp and webpmux_example.

Prerequisites:
A compiler (e.g., gcc with autotools) and gradle.
On a Debian-like system the following should install everything you need for a
minimal build:
$ sudo apt-get install build-essential gradle

When building from git sources, you will need to run the Gradle wrapper with the
appropriate target, e.g. :

./gradlew buildAllExecutables

SWIG bindings:
--------------

To generate language bindings from swig/libwebp.swig at least swig-1.3
(http://www.swig.org) is required.

Currently the following functions are mapped:
Decode:
  WebPGetDecoderVersion
  WebPGetInfo
  WebPDecodeRGBA
  WebPDecodeARGB
  WebPDecodeBGRA
  WebPDecodeBGR
  WebPDecodeRGB

Encode:
  WebPGetEncoderVersion
  WebPEncodeRGBA
  WebPEncodeBGRA
  WebPEncodeRGB
  WebPEncodeBGR
  WebPEncodeLosslessRGBA
  WebPEncodeLosslessBGRA
  WebPEncodeLosslessRGB
  WebPEncodeLosslessBGR

See swig/README for more detailed build instructions.

Java bindings:

To build the swig-generated JNI wrapper code at least JDK-1.5 (or equivalent)
is necessary for enum support. The output is intended to be a shared object /
DLL that can be loaded via System.loadLibrary("webp_jni").

Python bindings:

To build the swig-generated Python extension code at least Python 2.6 is
required. Python < 2.6 may build with some minor changes to libwebp.swig or the
generated code, but is untested.

Encoding tool:
==============

The examples/ directory contains tools for encoding (cwebp) and
decoding (dwebp) images.

The easiest use should look like:
  cwebp input.png -q 80 -o output.webp
which will convert the input file to a WebP file using a quality factor of 80
on a 0->100 scale (0 being the lowest quality, 100 being the best. Default
value is 75).
You might want to try the -lossless flag too, which will compress the source
(in RGBA format) without any loss. The -q quality parameter will in this case
control the amount of processing time spent trying to make the output file as
small as possible.

A longer list of options is available using the -longhelp command line flag:

> cwebp -longhelp
Usage:
 cwebp [-preset <...>] [options] in_file [-o out_file]

If input size (-s) for an image is not specified, it is
assumed to be a PNG, JPEG, TIFF or WebP file.

Options:
  -h / -help ............. short help
  -H / -longhelp ......... long help
  -q <float> ............. quality factor (0:small..100:big), default=75
  -alpha_q <int> ......... transparency-compression quality (0..100),
                           default=100
  -preset <string> ....... preset setting, one of:
                            default, photo, picture,
                            drawing, icon, text
     -preset must come first, as it overwrites other parameters
  -z <int> ............... activates lossless preset with given
                           level in [0:fast, ..., 9:slowest]

  -m <int> ............... compression method (0=fast, 6=slowest), default=4
  -segments <int> ........ number of segments to use (1..4), default=4
  -size <int> ............ target size (in bytes)
  -psnr <float> .......... target PSNR (in dB. typically: 42)

  -s <int> <int> ......... input size (width x height) for YUV
  -sns <int> ............. spatial noise shaping (0:off, 100:max), default=50
  -f <int> ............... filter strength (0=off..100), default=60
  -sharpness <int> ....... filter sharpness (0:most .. 7:least sharp), default=0
  -strong ................ use strong filter instead of simple (default)
  -nostrong .............. use simple filter instead of strong
  -sharp_yuv ............. use sharper (and slower) RGB->YUV conversion
  -partition_limit <int> . limit quality to fit the 512k limit on
                           the first partition (0=no degradation ... 100=full)
  -pass <int> ............ analysis pass number (1..10)
  -crop <x> <y> <w> <h> .. crop picture with the given rectangle
  -resize <w> <h> ........ resize picture (after any cropping)
  -mt .................... use multi-threading if available
  -low_memory ............ reduce memory usage (slower encoding)
  -map <int> ............. print map of extra info
  -print_psnr ............ prints averaged PSNR distortion
  -print_ssim ............ prints averaged SSIM distortion
  -print_lsim ............ prints local-similarity distortion
  -d <file.pgm> .......... dump the compressed output (PGM file)
  -alpha_method <int> .... transparency-compression method (0..1), default=1
  -alpha_filter <string> . predictive filtering for alpha plane,
                           one of: none, fast (default) or best
  -exact ................. preserve RGB values in transparent area, default=off
  -blend_alpha <hex> ..... blend colors against background color
                           expressed as RGB values written in
                           hexadecimal, e.g. 0xc0e0d0 for red=0xc0
                           green=0xe0 and blue=0xd0
  -noalpha ............... discard any transparency information
  -lossless .............. encode image losslessly, default=off
  -near_lossless <int> ... use near-lossless image
                           preprocessing (0..100=off), default=100
  -hint <string> ......... specify image characteristics hint,
                           one of: photo, picture or graph

  -metadata <string> ..... comma separated list of metadata to
                           copy from the input to the output if present.
                           Valid values: all, none (default), exif, icc, xmp

  -short ................. condense printed message
  -quiet ................. don't print anything
  -version ............... print version number and exit
  -noasm ................. disable all assembly optimizations
  -v ..................... verbose, e.g. print encoding/decoding times
  -progress .............. report encoding progress

Experimental Options:
  -jpeg_like ............. roughly match expected JPEG size
  -af .................... auto-adjust filter strength
  -pre <int> ............. pre-processing filter

The main options you might want to try in order to further tune the
visual quality are:
 -preset
 -sns
 -f
 -m

Namely:
  * 'preset' will set up a default encoding configuration targeting a
     particular type of input. It should appear first in the list of options,
     so that subsequent options can take effect on top of this preset.
     Default value is 'default'.
  * 'sns' will progressively turn on (when going from 0 to 100) some additional
     visual optimizations (like: segmentation map re-enforcement). This option
     will balance the bit allocation differently. It tries to take bits from the
     "easy" parts of the picture and use them in the "difficult" ones instead.
     Usually, raising the sns value (at fixed -q value) leads to larger files,
     but with better quality.
     Typical value is around '75'.
  * 'f' option directly links to the filtering strength used by the codec's
     in-loop processing. The higher the value, the smoother the
     highly-compressed area will look. This is particularly useful when aiming
     at very small files. Typical values are around 20-30. Note that using the
     option -strong/-nostrong will change the type of filtering. Use "-f 0" to
     turn filtering off.
  * 'm' controls the trade-off between encoding speed and quality. Default is 4.
     You can try -m 5 or -m 6 to explore more (time-consuming) encoding
     possibilities. A lower value will result in faster encoding at the expense
     of quality.

Decoding tool:
==============

There is a decoding sample in examples/dwebp.c which will take
a .webp file and decode it to a PNG image file (amongst other formats).
This is simply to demonstrate the use of the API. You can verify the
file test.webp decodes to exactly the same as test_ref.ppm by using:

 cd examples
 ./dwebp test.webp -ppm -o test.ppm
 diff test.ppm test_ref.ppm

The full list of options is available using -h:

> dwebp -h
Usage: dwebp in_file [options] [-o out_file]

Decodes the WebP image file to PNG format [Default]
Use following options to convert into alternate image formats:
  -pam ......... save the raw RGBA samples as a color PAM
  -ppm ......... save the raw RGB samples as a color PPM
  -bmp ......... save as uncompressed BMP format
  -tiff ........ save as uncompressed TIFF format
  -pgm ......... save the raw YUV samples as a grayscale PGM
                 file with IMC4 layout
  -yuv ......... save the raw YUV samples in flat layout

 Other options are:
  -version ..... print version number and exit
  -nofancy ..... don't use the fancy YUV420 upscaler
  -nofilter .... disable in-loop filtering
  -nodither .... disable dithering
  -dither <d> .. dithering strength (in 0..100)
  -alpha_dither  use alpha-plane dithering if needed
  -mt .......... use multi-threading
  -crop <x> <y> <w> <h> ... crop output with the given rectangle
  -resize <w> <h> ......... scale the output (*after* any cropping)
  -flip ........ flip the output vertically
  -alpha ....... only save the alpha plane
  -incremental . use incremental decoding (useful for tests)
  -h ........... this help message
  -v ........... verbose (e.g. print encoding/decoding times)
  -quiet ....... quiet mode, don't print anything
  -noasm ....... disable all assembly optimizations

WebP file analysis tool:
========================

'webpinfo' can be used to print out the chunk level structure and bitstream
header information of WebP files. It can also check if the files are of valid
WebP format.

Usage: webpinfo [options] in_files
Note: there could be multiple input files;
      options must come before input files.
Options:
  -version ........... Print version number and exit.
  -quiet ............. Do not show chunk parsing information.
  -diag .............. Show parsing error diagnosis.
  -summary ........... Show chunk stats summary.
  -bitstream_info .... Parse bitstream header.

Visualization tool:
===================

There's a little self-serve visualization tool called 'vwebp' under the
examples/ directory. It uses OpenGL to open a simple drawing window and show
a decoded WebP file. It's not yet integrated in the automake build system, but
you can try to manually compile it using the recommendations below.

Usage: vwebp in_file [options]

Decodes the WebP image file and visualize it using OpenGL
Options are:
  -version ..... print version number and exit
  -noicc ....... don't use the icc profile if present
  -nofancy ..... don't use the fancy YUV420 upscaler
  -nofilter .... disable in-loop filtering
  -dither <int>  dithering strength (0..100), default=50
  -noalphadither disable alpha plane dithering
  -usebgcolor .. display background color
  -mt .......... use multi-threading
  -info ........ print info
  -h ........... this help message

Keyboard shortcuts:
  'c' ................ toggle use of color profile
  'b' ................ toggle background color display
  'i' ................ overlay file information
  'd' ................ disable blending & disposal (debug)
  'q' / 'Q' / ESC .... quit

Building:
---------

Prerequisites:
1) OpenGL & OpenGL Utility Toolkit (GLUT)
  Linux:
    $ sudo apt-get install freeglut3-dev mesa-common-dev
  Mac + XCode:
    - These libraries should be available in the OpenGL / GLUT frameworks.
  Windows:
    http://freeglut.sourceforge.net/index.php#download

2) (Optional) qcms (Quick Color Management System)
  i. Download qcms from Mozilla / Chromium:
    http://hg.mozilla.org/mozilla-central/file/0e7639e3bdfb/gfx/qcms
    http://src.chromium.org/viewvc/chrome/trunk/src/third_party/qcms
  ii. Build and archive the source files as libqcms.a / qcms.lib
  iii. Update makefile.unix / Makefile.vc
    a) Define WEBP_HAVE_QCMS
    b) Update include / library paths to reference the qcms directory.

Build using makefile.unix / Makefile.vc:
$ make -f makefile.unix examples/vwebp
> nmake /f Makefile.vc CFG=release-static \
    ../obj/x64/release-static/bin/vwebp.exe

Animation creation tool:
========================
The utility 'img2webp' can turn a sequence of input images (PNG, JPEG, ...)
into an animated WebP file. It offers fine control over duration, encoding
modes, etc.

Usage:

  img2webp [file-level options] [image files...] [per-frame options...]

File-level options (only used at the start of compression):
 -min_size ............ minimize size
 -loop <int> .......... loop count (default: 0, = infinite loop)
 -kmax <int> .......... maximum number of frame between key-frames
                        (0=only keyframes)
 -kmin <int> .......... minimum number of frame between key-frames
                        (0=disable key-frames altogether)
 -mixed ............... use mixed lossy/lossless automatic mode
 -v ................... verbose mode
 -h ................... this help
 -version ............. print version number and exit

Per-frame options (only used for subsequent images input):
 -d <int> ............. frame duration in ms (default: 100)
 -lossless  ........... use lossless mode (default)
 -lossy ... ........... use lossy mode
 -q <float> ........... quality
 -m <int> ............. method to use

example: img2webp -loop 2 in0.png -lossy in1.jpg
                  -d 80 in2.tiff -o out.webp

Note: if a single file name is passed as the argument, the arguments will be
tokenized from this file. The file name must not start with the character '-'.

Animated GIF conversion:
========================
Animated GIF files can be converted to WebP files with animation using the
gif2webp utility available under examples/. The files can then be viewed using
vwebp.

Usage:
 gif2webp [options] gif_file -o webp_file
Options:
  -h / -help ............. this help
  -lossy ................. encode image using lossy compression
  -mixed ................. for each frame in the image, pick lossy
                           or lossless compression heuristically
  -q <float> ............. quality factor (0:small..100:big)
  -m <int> ............... compression method (0=fast, 6=slowest)
  -min_size .............. minimize output size (default:off)
                           lossless compression by default; can be
                           combined with -q, -m, -lossy or -mixed
                           options
  -kmin <int> ............ min distance between key frames
  -kmax <int> ............ max distance between key frames
  -f <int> ............... filter strength (0=off..100)
  -metadata <string> ..... comma separated list of metadata to
                           copy from the input to the output if present
                           Valid values: all, none, icc, xmp (default)
  -loop_compatibility .... use compatibility mode for Chrome
                           version prior to M62 (inclusive)
  -mt .................... use multi-threading if available

  -version ............... print version number and exit
  -v ..................... verbose
  -quiet ................. don't print anything

Building:
---------
With the libgif development files installed, gif2webp can be built using
makefile.unix:
$ make -f makefile.unix examples/gif2webp

or using autoconf:
$ ./configure --enable-everything
$ make

Comparison of animated images:
==============================
Test utility anim_diff under examples/ can be used to compare two animated
images (each can be GIF or WebP).

Usage: anim_diff <image1> <image2> [options]

Options:
  -dump_frames <folder> dump decoded frames in PAM format
  -min_psnr <float> ... minimum per-frame PSNR
  -raw_comparison ..... if this flag is not used, RGB is
                        premultiplied before comparison
  -max_diff <int> ..... maximum allowed difference per channel
                        between corresponding pixels in subsequent
                        frames
  -h .................. this help
  -version ............ print version number and exit

Building:
---------
With the libgif development files and a C++ compiler installed, anim_diff can
be built using makefile.unix:
$ make -f makefile.unix examples/anim_diff

or using autoconf:
$ ./configure --enable-everything
$ make

Encoding API:
=============

The main encoding functions are available in the header src/webp/encode.h
The ready-to-use ones are:
size_t WebPEncodeRGB(const uint8_t* rgb, int width, int height, int stride,
                     float quality_factor, uint8_t** output);
size_t WebPEncodeBGR(const uint8_t* bgr, int width, int height, int stride,
                     float quality_factor, uint8_t** output);
size_t WebPEncodeRGBA(const uint8_t* rgba, int width, int height, int stride,
                      float quality_factor, uint8_t** output);
size_t WebPEncodeBGRA(const uint8_t* bgra, int width, int height, int stride,
                      float quality_factor, uint8_t** output);

They will convert raw RGB samples to a WebP data. The only control supplied
is the quality factor.

There are some variants for using the lossless format:

size_t WebPEncodeLosslessRGB(const uint8_t* rgb, int width, int height,
                             int stride, uint8_t** output);
size_t WebPEncodeLosslessBGR(const uint8_t* bgr, int width, int height,
                             int stride, uint8_t** output);
size_t WebPEncodeLosslessRGBA(const uint8_t* rgba, int width, int height,
                              int stride, uint8_t** output);
size_t WebPEncodeLosslessBGRA(const uint8_t* bgra, int width, int height,
                              int stride, uint8_t** output);

Of course in this case, no quality factor is needed since the compression
occurs without loss of the input values, at the expense of larger output sizes.

Advanced encoding API:
----------------------

A more advanced API is based on the WebPConfig and WebPPicture structures.

WebPConfig contains the encoding settings and is not tied to a particular
picture.
WebPPicture contains input data, on which some WebPConfig will be used for
compression.
The encoding flow looks like:

-------------------------------------- BEGIN PSEUDO EXAMPLE

#include <webp/encode.h>

  // Setup a config, starting form a preset and tuning some additional
  // parameters
  WebPConfig config;
  if (!WebPConfigPreset(&config, WEBP_PRESET_PHOTO, quality_factor))
    return 0;   // version error
  }
  // ... additional tuning
  config.sns_strength = 90;
  config.filter_sharpness = 6;
  config_error = WebPValidateConfig(&config);  // not mandatory, but useful

  // Setup the input data
  WebPPicture pic;
  if (!WebPPictureInit(&pic)) {
    return 0;  // version error
  }
  pic.width = width;
  pic.height = height;
  // allocated picture of dimension width x height
  if (!WebPPictureAllocate(&pic)) {
    return 0;   // memory error
  }
  // at this point, 'pic' has been initialized as a container,
  // and can receive the Y/U/V samples.
  // Alternatively, one could use ready-made import functions like
  // WebPPictureImportRGB(), which will take care of memory allocation.
  // In any case, past this point, one will have to call
  // WebPPictureFree(&pic) to reclaim memory.

  // Set up a byte-output write method. WebPMemoryWriter, for instance.
  WebPMemoryWriter wrt;
  WebPMemoryWriterInit(&wrt);     // initialize 'wrt'

  pic.writer = MyFileWriter;
  pic.custom_ptr = my_opaque_structure_to_make_MyFileWriter_work;

  // Compress!
  int ok = WebPEncode(&config, &pic);   // ok = 0 => error occurred!
  WebPPictureFree(&pic);  // must be called independently of the 'ok' result.

  // output data should have been handled by the writer at that point.
  // -> compressed data is the memory buffer described by wrt.mem / wrt.size

  // deallocate the memory used by compressed data
  WebPMemoryWriterClear(&wrt);

-------------------------------------- END PSEUDO EXAMPLE

Decoding API:
=============

This is mainly just one function to call:

#include "webp/decode.h"
uint8_t* WebPDecodeRGB(const uint8_t* data, size_t data_size,
                       int* width, int* height);

Please have a look at the file src/webp/decode.h for the details.
There are variants for decoding in BGR/RGBA/ARGB/BGRA order, along with
decoding to raw Y'CbCr samples. One can also decode the image directly into a
pre-allocated buffer.

To detect a WebP file and gather the picture's dimensions, the function:
  int WebPGetInfo(const uint8_t* data, size_t data_size,
                  int* width, int* height);
is supplied. No decoding is involved when using it.

Incremental decoding API:
=========================

In the case when data is being progressively transmitted, pictures can still
be incrementally decoded using a slightly more complicated API. Decoder state
is stored into an instance of the WebPIDecoder object. This object can be
created with the purpose of decoding either RGB or Y'CbCr samples.
For instance:

  WebPDecBuffer buffer;
  WebPInitDecBuffer(&buffer);
  buffer.colorspace = MODE_BGR;
  ...
  WebPIDecoder* idec = WebPINewDecoder(&buffer);

As data is made progressively available, this incremental-decoder object
can be used to decode the picture further. There are two (mutually exclusive)
ways to pass freshly arrived data:

either by appending the fresh bytes:

  WebPIAppend(idec, fresh_data, size_of_fresh_data);

or by just mentioning the new size of the transmitted data:

  WebPIUpdate(idec, buffer, size_of_transmitted_buffer);

Note that 'buffer' can be modified between each call to WebPIUpdate, in
particular when the buffer is resized to accommodate larger data.

These functions will return the decoding status: either VP8_STATUS_SUSPENDED if
decoding is not finished yet or VP8_STATUS_OK when decoding is done. Any other
status is an error condition.

The 'idec' object must always be released (even upon an error condition) by
calling: WebPDelete(idec).

To retrieve partially decoded picture samples, one must use the corresponding
method: WebPIDecGetRGB or WebPIDecGetYUVA.
It will return the last displayable pixel row.

Lastly, note that decoding can also be performed into a pre-allocated pixel
buffer. This buffer must be passed when creating a WebPIDecoder, calling
WebPINewRGB() or WebPINewYUVA().

Please have a look at the src/webp/decode.h header for further details.

Advanced Decoding API:
======================

WebP decoding supports an advanced API which provides on-the-fly cropping and
rescaling, something of great usefulness on memory-constrained environments like
mobile phones. Basically, the memory usage will scale with the output's size,
not the input's, when one only needs a quick preview or a zoomed in portion of
an otherwise too-large picture. Some CPU can be saved too, incidentally.

-------------------------------------- BEGIN PSEUDO EXAMPLE
     // A) Init a configuration object
     WebPDecoderConfig config;
     CHECK(WebPInitDecoderConfig(&config));

     // B) optional: retrieve the bitstream's features.
     CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK);

     // C) Adjust 'config' options, if needed
     config.options.no_fancy_upsampling = 1;
     config.options.use_scaling = 1;
     config.options.scaled_width = scaledWidth();
     config.options.scaled_height = scaledHeight();
     // etc.

     // D) Specify 'config' output options for specifying output colorspace.
     // Optionally the external image decode buffer can also be specified.
     config.output.colorspace = MODE_BGRA;
     // Optionally, the config.output can be pointed to an external buffer as
     // well for decoding the image. This externally supplied memory buffer
     // should be big enough to store the decoded picture.
     config.output.u.RGBA.rgba = (uint8_t*) memory_buffer;
     config.output.u.RGBA.stride = scanline_stride;
     config.output.u.RGBA.size = total_size_of_the_memory_buffer;
     config.output.is_external_memory = 1;

     // E) Decode the WebP image. There are two variants w.r.t decoding image.
     // The first one (E.1) decodes the full image and the second one (E.2) is
     // used to incrementally decode the image using small input buffers.
     // Any one of these steps can be used to decode the WebP image.

     // E.1) Decode full image.
     CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK);

     // E.2) Decode image incrementally.
     WebPIDecoder* const idec = WebPIDecode(NULL, NULL, &config);
     CHECK(idec != NULL);
     while (bytes_remaining > 0) {
       VP8StatusCode status = WebPIAppend(idec, input, bytes_read);
       if (status == VP8_STATUS_OK || status == VP8_STATUS_SUSPENDED) {
         bytes_remaining -= bytes_read;
       } else {
         break;
       }
     }
     WebPIDelete(idec);

     // F) Decoded image is now in config.output (and config.output.u.RGBA).
     // It can be saved, displayed or otherwise processed.

     // G) Reclaim memory allocated in config's object. It's safe to call
     // this function even if the memory is external and wasn't allocated
     // by WebPDecode().
     WebPFreeDecBuffer(&config.output);

-------------------------------------- END PSEUDO EXAMPLE

Bugs:
=====

Please report all bugs to the issue tracker:
    https://bugs.chromium.org/p/webp
Patches welcome! See this page to get started:
    http://www.webmproject.org/code/contribute/submitting-patches/

Discuss:
========

Email: webp-discuss@webmproject.org
Web: http://groups.google.com/a/webmproject.org/group/webp-discuss