"Fossies" - the Fresh Open Source Software Archive

Member "firefox-69.0.1/media/libwebp/README" (17 Sep 2019, 30025 Bytes) of package /linux/www/firefox-69.0.1.source.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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@webmproject.org
  789 Web: http://groups.google.com/a/webmproject.org/group/webp-discuss