media/libwebp/README

   1           __   __  ____  ____  ____
   2          /  \\/  \/  _ \/  _ )/  _ \
   3          \       /   __/  _  \   __/
   4           \__\__/\____/\_____/__/ ____  ___
   5                 / _/ /    \    \ /  _ \/ _/
   6                /  \_/   / /   \ \   __/  \__
   7                \____/____/\_____/_____/____/v1.2.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 https://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 https://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, gif2webp, 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 Note: Animated PNG and WebP files are not supported.
 229
 230 Options:
 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
 295 Experimental Options:
 296   -jpeg_like ............. roughly match expected JPEG size
 297   -af .................... auto-adjust filter strength
 298   -pre <int> ............. pre-processing filter
 299
 300
 301 The main options you might want to try in order to further tune the
 302 visual quality are:
 303  -preset
 304  -sns
 305  -f
 306  -m
 307
 308 Namely:
 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
 331 Decoding tool:
 332 ==============
 333
 334 There is a decoding sample in examples/dwebp.c which will take
 335 a .webp file and decode it to a PNG image file (amongst other formats).
 336 This is simply to demonstrate the use of the API. You can verify the
 337 file 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
 343 The full list of options is available using -h:
 344
 345 > dwebp -h
 346 Usage: dwebp in_file [options] [-o out_file]
 347
 348 Decodes the WebP image file to PNG format [Default].
 349 Note: Animated WebP files are not supported.
 350
 351 Use 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
 378 WebP file analysis tool:
 379 ========================
 380
 381 'webpinfo' can be used to print out the chunk level structure and bitstream
 382 header information of WebP files. It can also check if the files are of valid
 383 WebP format.
 384
 385 Usage: webpinfo [options] in_files
 386 Note: there could be multiple input files;
 387       options must come before input files.
 388 Options:
 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
 395 Visualization tool:
 396 ===================
 397
 398 There's a little self-serve visualization tool called 'vwebp' under the
 399 examples/ directory. It uses OpenGL to open a simple drawing window and show
 400 a decoded WebP file. It's not yet integrated in the automake build system, but
 401 you can try to manually compile it using the recommendations below.
 402
 403 Usage: vwebp in_file [options]
 404
 405 Decodes the WebP image file and visualize it using OpenGL
 406 Options 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
 418 Keyboard 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
 425 Building:
 426 ---------
 427
 428 Prerequisites:
 429 1) 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
 437 2) (Optional) qcms (Quick Color Management System)
 438   i. Download qcms from Mozilla / Chromium:
 439     https://hg.mozilla.org/mozilla-central/file/0e7639e3bdfb/gfx/qcms
 440     https://source.chromium.org/chromium/chromium/src/+/main:third_party/qcms/;drc=d4a2f8e1ed461d8fc05ed88d1ae2dc94c9773825
 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
 446 Build 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
 451 Animation creation tool:
 452 ========================
 453 The utility 'img2webp' can turn a sequence of input images (PNG, JPEG, ...)
 454 into an animated WebP file. It offers fine control over duration, encoding
 455 modes, etc.
 456
 457 Usage:
 458
 459   img2webp [file_options] [[frame_options] frame_file]...
 460
 461 File-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
 473 Per-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
 480 example: img2webp -loop 2 in0.png -lossy in1.jpg
 481                   -d 80 in2.tiff -o out.webp
 482
 483 Note: if a single file name is passed as the argument, the arguments will be
 484 tokenized from this file. The file name must not start with the character '-'.
 485
 486 Animated GIF conversion:
 487 ========================
 488 Animated GIF files can be converted to WebP files with animation using the
 489 gif2webp utility available under examples/. The files can then be viewed using
 490 vwebp.
 491
 492 Usage:
 493  gif2webp [options] gif_file -o webp_file
 494 Options:
 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
 519 Building:
 520 ---------
 521 With the libgif development files installed, gif2webp can be built using
 522 makefile.unix:
 523 $ make -f makefile.unix examples/gif2webp
 524
 525 or using autoconf:
 526 $ ./configure --enable-everything
 527 $ make
 528
 529 Comparison of animated images:
 530 ==============================
 531 Test utility anim_diff under examples/ can be used to compare two animated
 532 images (each can be GIF or WebP).
 533
 534 Usage: anim_diff <image1> <image2> [options]
 535
 536 Options:
 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
 547 Building:
 548 ---------
 549 With the libgif development files and a C++ compiler installed, anim_diff can
 550 be built using makefile.unix:
 551 $ make -f makefile.unix examples/anim_diff
 552
 553 or using autoconf:
 554 $ ./configure --enable-everything
 555 $ make
 556
 557 Encoding API:
 558 =============
 559
 560 The main encoding functions are available in the header src/webp/encode.h
 561 The ready-to-use ones are:
 562 size_t WebPEncodeRGB(const uint8_t* rgb, int width, int height, int stride,
 563                      float quality_factor, uint8_t** output);
 564 size_t WebPEncodeBGR(const uint8_t* bgr, int width, int height, int stride,
 565                      float quality_factor, uint8_t** output);
 566 size_t WebPEncodeRGBA(const uint8_t* rgba, int width, int height, int stride,
 567                       float quality_factor, uint8_t** output);
 568 size_t WebPEncodeBGRA(const uint8_t* bgra, int width, int height, int stride,
 569                       float quality_factor, uint8_t** output);
 570
 571 They will convert raw RGB samples to a WebP data. The only control supplied
 572 is the quality factor.
 573
 574 There are some variants for using the lossless format:
 575
 576 size_t WebPEncodeLosslessRGB(const uint8_t* rgb, int width, int height,
 577                              int stride, uint8_t** output);
 578 size_t WebPEncodeLosslessBGR(const uint8_t* bgr, int width, int height,
 579                              int stride, uint8_t** output);
 580 size_t WebPEncodeLosslessRGBA(const uint8_t* rgba, int width, int height,
 581                               int stride, uint8_t** output);
 582 size_t WebPEncodeLosslessBGRA(const uint8_t* bgra, int width, int height,
 583                               int stride, uint8_t** output);
 584
 585 Of course in this case, no quality factor is needed since the compression
 586 occurs without loss of the input values, at the expense of larger output sizes.
 587
 588 Advanced encoding API:
 589 ----------------------
 590
 591 A more advanced API is based on the WebPConfig and WebPPicture structures.
 592
 593 WebPConfig contains the encoding settings and is not tied to a particular
 594 picture.
 595 WebPPicture contains input data, on which some WebPConfig will be used for
 596 compression.
 597 The 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 (!WebPPictureAlloc(&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
 651 Decoding API:
 652 =============
 653
 654 This is mainly just one function to call:
 655
 656 #include "webp/decode.h"
 657 uint8_t* WebPDecodeRGB(const uint8_t* data, size_t data_size,
 658                        int* width, int* height);
 659
 660 Please have a look at the file src/webp/decode.h for the details.
 661 There are variants for decoding in BGR/RGBA/ARGB/BGRA order, along with
 662 decoding to raw Y'CbCr samples. One can also decode the image directly into a
 663 pre-allocated buffer.
 664
 665 To 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);
 668 is supplied. No decoding is involved when using it.
 669
 670 Incremental decoding API:
 671 =========================
 672
 673 In the case when data is being progressively transmitted, pictures can still
 674 be incrementally decoded using a slightly more complicated API. Decoder state
 675 is stored into an instance of the WebPIDecoder object. This object can be
 676 created with the purpose of decoding either RGB or Y'CbCr samples.
 677 For instance:
 678
 679   WebPDecBuffer buffer;
 680   WebPInitDecBuffer(&buffer);
 681   buffer.colorspace = MODE_BGR;
 682   ...
 683   WebPIDecoder* idec = WebPINewDecoder(&buffer);
 684
 685 As data is made progressively available, this incremental-decoder object
 686 can be used to decode the picture further. There are two (mutually exclusive)
 687 ways to pass freshly arrived data:
 688
 689 either by appending the fresh bytes:
 690
 691   WebPIAppend(idec, fresh_data, size_of_fresh_data);
 692
 693 or by just mentioning the new size of the transmitted data:
 694
 695   WebPIUpdate(idec, buffer, size_of_transmitted_buffer);
 696
 697 Note that 'buffer' can be modified between each call to WebPIUpdate, in
 698 particular when the buffer is resized to accommodate larger data.
 699
 700 These functions will return the decoding status: either VP8_STATUS_SUSPENDED if
 701 decoding is not finished yet or VP8_STATUS_OK when decoding is done. Any other
 702 status is an error condition.
 703
 704 The 'idec' object must always be released (even upon an error condition) by
 705 calling: WebPDelete(idec).
 706
 707 To retrieve partially decoded picture samples, one must use the corresponding
 708 method: WebPIDecGetRGB or WebPIDecGetYUVA.
 709 It will return the last displayable pixel row.
 710
 711 Lastly, note that decoding can also be performed into a pre-allocated pixel
 712 buffer. This buffer must be passed when creating a WebPIDecoder, calling
 713 WebPINewRGB() or WebPINewYUVA().
 714
 715 Please have a look at the src/webp/decode.h header for further details.
 716
 717 Advanced Decoding API:
 718 ======================
 719
 720 WebP decoding supports an advanced API which provides on-the-fly cropping and
 721 rescaling, something of great usefulness on memory-constrained environments like
 722 mobile phones. Basically, the memory usage will scale with the output's size,
 723 not the input's, when one only needs a quick preview or a zoomed in portion of
 724 an 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
 783 Bugs:
 784 =====
 785
 786 Please report all bugs to the issue tracker:
 787     https://bugs.chromium.org/p/webp
 788 Patches welcome! See this page to get started:
 789     https://www.webmproject.org/code/contribute/submitting-patches/
 790
 791 Discuss:
 792 ========
 793
 794 Email: webp-discuss@webmproject.org
 795 Web: https://groups.google.com/a/webmproject.org/group/webp-discuss