Home | History | Annotate | only in /external/webp
Up to higher level directory
NameDateSize
Android.mk09-Oct-201337
AUTHORS09-Oct-2013144
ChangeLog09-Oct-2013314
COPYING09-Oct-20131.5K
examples/09-Oct-2013
include/09-Oct-2013
INSTALL09-Oct-20139.3K
NEWS09-Oct-2013143
PATENTS09-Oct-20131.3K
README09-Oct-201319.1K
README.android09-Oct-20132K
src/09-Oct-2013

README

      1           __   __  ____  ____  ____
      2          /  \\/  \/  _ \/  _ )/  _ \
      3          \       /   __/  _  \   __/
      4           \__\__/\____/\_____/__/ ____  ___
      5                 / _/ /    \    \ /  _ \/ _/
      6                /  \_/   / /   \ \   __/  \__
      7                \____/____/\_____/_____/____/v0.2.1
      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 Latest sources are available from http://www.webmproject.org/code/
     19 
     20 It is released under the same license as the WebM project.
     21 See http://www.webmproject.org/license/software/ or the
     22 file "COPYING" file for details. An additional intellectual
     23 property rights grant can be found in the file PATENTS.
     24 
     25 Building:
     26 =========
     27 
     28 Windows build:
     29 --------------
     30 
     31 By running:
     32 
     33   nmake /f Makefile.vc CFG=release-static RTLIBCFG=static OBJDIR=output
     34 
     35 the directory output\release-static\(x64|x86)\bin will contain the tools
     36 cwebp.exe and dwebp.exe. The directory output\release-static\(x64|x86)\lib will
     37 contain the libwebp static library.
     38 The target architecture (x86/x64) is detected by Makefile.vc from the Visual
     39 Studio compiler (cl.exe) available in the system path.
     40 
     41 Unix build using makefile.unix:
     42 -------------------------------
     43 
     44 On platforms with GNU tools installed (gcc and make), running
     45 
     46   make -f makefile.unix
     47 
     48 will build the binaries examples/cwebp and examples/dwebp, along
     49 with the static library src/libwebp.a. No system-wide installation
     50 is supplied, as this is a simple alternative to the full installation
     51 system based on the autoconf tools (see below).
     52 Please refer to the makefile.unix for additional details and customizations.
     53 
     54 Using autoconf tools:
     55 ---------------------
     56 When building from git sources, you will need to run autogen.sh to generate the
     57 configure script.
     58 
     59 ./configure
     60 make
     61 make install
     62 
     63 should be all you need to have the following files
     64 
     65 /usr/local/include/webp/decode.h
     66 /usr/local/include/webp/encode.h
     67 /usr/local/include/webp/types.h
     68 /usr/local/lib/libwebp.*
     69 /usr/local/bin/cwebp
     70 /usr/local/bin/dwebp
     71 
     72 installed.
     73 
     74 Note: The encoding and decoding libraries are compiled separately
     75 (as src/dec/libwebpdecode.* and src/dec/libwebpencode.*). They
     76 can be installed independently using a minor modification in the
     77 corresponding Makefile.am configure files (see comments there).
     78 
     79 SWIG bindings:
     80 --------------
     81 
     82 To generate language bindings from swig/libwebp.i swig-1.3
     83 (http://www.swig.org) is required. 2.0 may work, but has not been tested.
     84 
     85 Currently the following functions are mapped:
     86 Decode:
     87   WebPGetDecoderVersion
     88   WebPGetInfo
     89   WebPDecodeRGBA
     90   WebPDecodeARGB
     91   WebPDecodeBGRA
     92   WebPDecodeBGR
     93   WebPDecodeRGB
     94 
     95 Encode:
     96   WebPGetEncoderVersion
     97   WebPEncodeRGBA
     98   WebPEncodeBGRA
     99   WebPEncodeRGB
    100   WebPEncodeBGR
    101   WebPEncodeLosslessRGBA
    102   WebPEncodeLosslessBGRA
    103   WebPEncodeLosslessRGB
    104   WebPEncodeLosslessBGR
    105 
    106 Java bindings:
    107 
    108 To build the swig-generated JNI wrapper code at least JDK-1.5 (or equivalent)
    109 is necessary for enum support. The output is intended to be a shared object /
    110 DLL that can be loaded via System.loadLibrary("webp_jni").
    111 
    112 Encoding tool:
    113 ==============
    114 
    115 The examples/ directory contains tools for encoding (cwebp) and
    116 decoding (dwebp) images.
    117 
    118 The easiest use should look like:
    119   cwebp input.png -q 80 -o output.webp
    120 which will convert the input file to a WebP file using a quality factor of 80
    121 on a 0->100 scale (0 being the lowest quality, 100 being the best. Default
    122 value is 75).
    123 You might want to try the -lossless flag too, which will compress the source
    124 (in RGBA format) without any loss. The -q quality parameter will in this case
    125 control the amount of processing time spent trying to make the output file as
    126 small as possible.
    127 
    128 A longer list of options is available using the -longhelp command line flag:
    129 
    130 > cwebp -longhelp
    131 Usage:
    132  cwebp [-preset <...>] [options] in_file [-o out_file]
    133 
    134 If input size (-s) for an image is not specified, it is assumed to be a PNG,
    135 JPEG or TIFF file.
    136 options:
    137   -h / -help  ............ short help
    138   -H / -longhelp  ........ long help
    139   -q <float> ............. quality factor (0:small..100:big)
    140   -alpha_q <int> ......... Transparency-compression quality (0..100).
    141   -preset <string> ....... Preset setting, one of:
    142                             default, photo, picture,
    143                             drawing, icon, text
    144      -preset must come first, as it overwrites other parameters.
    145   -m <int> ............... compression method (0=fast, 6=slowest)
    146   -segments <int> ........ number of segments to use (1..4)
    147   -size <int> ............ Target size (in bytes)
    148   -psnr <float> .......... Target PSNR (in dB. typically: 42)
    149 
    150   -s <int> <int> ......... Input size (width x height) for YUV
    151   -sns <int> ............. Spatial Noise Shaping (0:off, 100:max)
    152   -f <int> ............... filter strength (0=off..100)
    153   -sharpness <int> ....... filter sharpness (0:most .. 7:least sharp)
    154   -strong ................ use strong filter instead of simple (default).
    155   -nostrong .............. use simple filter instead of strong.
    156   -partition_limit <int> . limit quality to fit the 512k limit on
    157                            the first partition (0=no degradation ... 100=full)
    158   -pass <int> ............ analysis pass number (1..10)
    159   -crop <x> <y> <w> <h> .. crop picture with the given rectangle
    160   -resize <w> <h> ........ resize picture (after any cropping)
    161   -mt .................... use multi-threading if available
    162   -low_memory ............ reduce memory usage (slower encoding)
    163   -map <int> ............. print map of extra info.
    164   -print_psnr ............ prints averaged PSNR distortion.
    165   -print_ssim ............ prints averaged SSIM distortion.
    166   -print_lsim ............ prints local-similarity distortion.
    167   -d <file.pgm> .......... dump the compressed output (PGM file).
    168   -alpha_method <int> .... Transparency-compression method (0..1)
    169   -alpha_filter <string> . predictive filtering for alpha plane.
    170                            One of: none, fast (default) or best.
    171   -alpha_cleanup ......... Clean RGB values in transparent area.
    172   -noalpha ............... discard any transparency information.
    173   -lossless .............. Encode image losslessly.
    174   -hint <string> ......... Specify image characteristics hint.
    175                            One of: photo, picture or graph
    176 
    177   -metadata <string> ..... comma separated list of metadata to
    178                            copy from the input to the output if present.
    179                            Valid values: all, none (default), exif, iccp, xmp
    180 
    181   -short ................. condense printed message
    182   -quiet ................. don't print anything.
    183   -version ............... print version number and exit.
    184   -noasm ................. disable all assembly optimizations.
    185   -v ..................... verbose, e.g. print encoding/decoding times
    186   -progress .............. report encoding progress
    187 
    188 Experimental Options:
    189   -jpeg_like ............. Roughly match expected JPEG size.
    190   -af .................... auto-adjust filter strength.
    191   -pre <int> ............. pre-processing filter
    192 
    193 
    194 The main options you might want to try in order to further tune the
    195 visual quality are:
    196  -preset
    197  -sns
    198  -f
    199  -m
    200 
    201 Namely:
    202   * 'preset' will set up a default encoding configuration targeting a
    203      particular type of input. It should appear first in the list of options,
    204      so that subsequent options can take effect on top of this preset.
    205      Default value is 'default'.
    206   * 'sns' will progressively turn on (when going from 0 to 100) some additional
    207      visual optimizations (like: segmentation map re-enforcement). This option
    208      will balance the bit allocation differently. It tries to take bits from the
    209      "easy" parts of the picture and use them in the "difficult" ones instead.
    210      Usually, raising the sns value (at fixed -q value) leads to larger files,
    211      but with better quality.
    212      Typical value is around '75'.
    213   * 'f' option directly links to the filtering strength used by the codec's
    214      in-loop processing. The higher the value, the smoother the
    215      highly-compressed area will look. This is particularly useful when aiming
    216      at very small files. Typical values are around 20-30. Note that using the
    217      option -strong/-nostrong will change the type of filtering. Use "-f 0" to
    218      turn filtering off.
    219   * 'm' controls the trade-off between encoding speed and quality. Default is 4.
    220      You can try -m 5 or -m 6 to explore more (time-consuming) encoding
    221      possibilities. A lower value will result in faster encoding at the expense
    222      of quality.
    223 
    224 Decoding tool:
    225 ==============
    226 
    227 There is a decoding sample in examples/dwebp.c which will take
    228 a .webp file and decode it to a PNG image file (amongst other formats).
    229 This is simply to demonstrate the use of the API. You can verify the
    230 file test.webp decodes to exactly the same as test_ref.ppm by using:
    231 
    232  cd examples
    233  ./dwebp test.webp -ppm -o test.ppm
    234  diff test.ppm test_ref.ppm
    235 
    236 The full list of options is available using -h:
    237 
    238 > dwebp -h
    239 Usage: dwebp in_file [options] [-o out_file]
    240 
    241 Decodes the WebP image file to PNG format [Default]
    242 Use following options to convert into alternate image formats:
    243   -pam ......... save the raw RGBA samples as a color PAM
    244   -ppm ......... save the raw RGB samples as a color PPM
    245   -pgm ......... save the raw YUV samples as a grayscale PGM
    246                  file with IMC4 layout.
    247   -yuv ......... save the raw YUV samples in flat layout.
    248 
    249  Other options are:
    250   -version  .... print version number and exit.
    251   -nofancy ..... don't use the fancy YUV420 upscaler.
    252   -nofilter .... disable in-loop filtering.
    253   -mt .......... use multi-threading
    254   -crop <x> <y> <w> <h> ... crop output with the given rectangle
    255   -scale <w> <h> .......... scale the output (*after* any cropping)
    256   -alpha ....... only save the alpha plane.
    257   -h     ....... this help message.
    258   -v     ....... verbose (e.g. print encoding/decoding times)
    259   -noasm ....... disable all assembly optimizations.
    260 
    261 Visualization tool:
    262 ===================
    263 
    264 There's a little self-serve visualization tool called 'vwebp' under the
    265 examples/ directory. It uses OpenGL to open a simple drawing window and show
    266 a decoded WebP file. It's not yet integrated in the automake or makefile.unix
    267 build system, but you can try to manually compile it using the recommendations
    268 at the top of the source file.
    269 
    270 Usage: 'vwebp my_picture.webp'
    271 
    272 
    273 Encoding API:
    274 =============
    275 
    276 The main encoding functions are available in the header src/webp/encode.h
    277 The ready-to-use ones are:
    278 size_t WebPEncodeRGB(const uint8_t* rgb, int width, int height, int stride,
    279                      float quality_factor, uint8_t** output);
    280 size_t WebPEncodeBGR(const uint8_t* bgr, int width, int height, int stride,
    281                      float quality_factor, uint8_t** output);
    282 size_t WebPEncodeRGBA(const uint8_t* rgba, int width, int height, int stride,
    283                       float quality_factor, uint8_t** output);
    284 size_t WebPEncodeBGRA(const uint8_t* bgra, int width, int height, int stride,
    285                       float quality_factor, uint8_t** output);
    286 
    287 They will convert raw RGB samples to a WebP data. The only control supplied
    288 is the quality factor.
    289 
    290 There are some variants for using the lossless format:
    291 
    292 size_t WebPEncodeLosslessRGB(const uint8_t* rgb, int width, int height,
    293                              int stride, uint8_t** output);
    294 size_t WebPEncodeLosslessBGR(const uint8_t* bgr, int width, int height,
    295                              int stride, uint8_t** output);
    296 size_t WebPEncodeLosslessRGBA(const uint8_t* rgba, int width, int height,
    297                               int stride, uint8_t** output);
    298 size_t WebPEncodeLosslessBGRA(const uint8_t* bgra, int width, int height,
    299                               int stride, uint8_t** output);
    300 
    301 Of course in this case, no quality factor is needed since the compression
    302 occurs without loss of the input values, at the expense of larger output sizes.
    303 
    304 Advanced encoding API:
    305 ----------------------
    306 
    307 A more advanced API is based on the WebPConfig and WebPPicture structures.
    308 
    309 WebPConfig contains the encoding settings and is not tied to a particular
    310 picture.
    311 WebPPicture contains input data, on which some WebPConfig will be used for
    312 compression.
    313 The encoding flow looks like:
    314 
    315 -------------------------------------- BEGIN PSEUDO EXAMPLE
    316 
    317 #include <webp/encode.h>
    318 
    319   // Setup a config, starting form a preset and tuning some additional
    320   // parameters
    321   WebPConfig config;
    322   if (!WebPConfigPreset(&config, WEBP_PRESET_PHOTO, quality_factor))
    323     return 0;   // version error
    324   }
    325   // ... additional tuning
    326   config.sns_strength = 90;
    327   config.filter_sharpness = 6;
    328   config_error = WebPValidateConfig(&config);  // not mandatory, but useful
    329 
    330   // Setup the input data
    331   WebPPicture pic;
    332   if (!WebPPictureInit(&pic)) {
    333     return 0;  // version error
    334   }
    335   pic.width = width;
    336   pic.height = height;
    337   // allocated picture of dimension width x height
    338   if (!WebPPictureAllocate(&pic)) {
    339     return 0;   // memory error
    340   }
    341   // at this point, 'pic' has been initialized as a container,
    342   // and can receive the Y/U/V samples.
    343   // Alternatively, one could use ready-made import functions like
    344   // WebPPictureImportRGB(), which will take care of memory allocation.
    345   // In any case, past this point, one will have to call
    346   // WebPPictureFree(&pic) to reclaim memory.
    347 
    348   // Set up a byte-output write method. WebPMemoryWriter, for instance.
    349   WebPMemoryWriter wrt;
    350   pic.writer = MyFileWriter;
    351   pic.custom_ptr = my_opaque_structure_to_make_MyFileWriter_work;
    352   // initialize 'wrt' here...
    353 
    354   // Compress!
    355   int ok = WebPEncode(&config, &pic);   // ok = 0 => error occurred!
    356   WebPPictureFree(&pic);  // must be called independently of the 'ok' result.
    357 
    358   // output data should have been handled by the writer at that point.
    359 
    360 -------------------------------------- END PSEUDO EXAMPLE
    361 
    362 Decoding API:
    363 =============
    364 
    365 This is mainly just one function to call:
    366 
    367 #include "webp/decode.h"
    368 uint8_t* WebPDecodeRGB(const uint8_t* data, size_t data_size,
    369                        int* width, int* height);
    370 
    371 Please have a look at the file src/webp/decode.h for the details.
    372 There are variants for decoding in BGR/RGBA/ARGB/BGRA order, along with
    373 decoding to raw Y'CbCr samples. One can also decode the image directly into a
    374 pre-allocated buffer.
    375 
    376 To detect a WebP file and gather the picture's dimensions, the function:
    377   int WebPGetInfo(const uint8_t* data, size_t data_size,
    378                   int* width, int* height);
    379 is supplied. No decoding is involved when using it.
    380 
    381 Incremental decoding API:
    382 =========================
    383 
    384 In the case when data is being progressively transmitted, pictures can still
    385 be incrementally decoded using a slightly more complicated API. Decoder state
    386 is stored into an instance of the WebPIDecoder object. This object can be
    387 created with the purpose of decoding either RGB or Y'CbCr samples.
    388 For instance:
    389 
    390   WebPDecBuffer buffer;
    391   WebPInitDecBuffer(&buffer);
    392   buffer.colorspace = MODE_BGR;
    393   ...
    394   WebPIDecoder* idec = WebPINewDecoder(&buffer);
    395 
    396 As data is made progressively available, this incremental-decoder object
    397 can be used to decode the picture further. There are two (mutually exclusive)
    398 ways to pass freshly arrived data:
    399 
    400 either by appending the fresh bytes:
    401 
    402   WebPIAppend(idec, fresh_data, size_of_fresh_data);
    403 
    404 or by just mentioning the new size of the transmitted data:
    405 
    406   WebPIUpdate(idec, buffer, size_of_transmitted_buffer);
    407 
    408 Note that 'buffer' can be modified between each call to WebPIUpdate, in
    409 particular when the buffer is resized to accommodate larger data.
    410 
    411 These functions will return the decoding status: either VP8_STATUS_SUSPENDED if
    412 decoding is not finished yet or VP8_STATUS_OK when decoding is done. Any other
    413 status is an error condition.
    414 
    415 The 'idec' object must always be released (even upon an error condition) by
    416 calling: WebPDelete(idec).
    417 
    418 To retrieve partially decoded picture samples, one must use the corresponding
    419 method: WebPIDecGetRGB or WebPIDecGetYUVA.
    420 It will return the last displayable pixel row.
    421 
    422 Lastly, note that decoding can also be performed into a pre-allocated pixel
    423 buffer. This buffer must be passed when creating a WebPIDecoder, calling
    424 WebPINewRGB() or WebPINewYUVA().
    425 
    426 Please have a look at the src/webp/decode.h header for further details.
    427 
    428 Advanced Decoding API:
    429 ======================
    430 
    431 WebP decoding supports an advanced API which provides on-the-fly cropping and
    432 rescaling, something of great usefulness on memory-constrained environments like
    433 mobile phones. Basically, the memory usage will scale with the output's size,
    434 not the input's, when one only needs a quick preview or a zoomed in portion of
    435 an otherwise too-large picture. Some CPU can be saved too, incidentally.
    436 
    437 -------------------------------------- BEGIN PSEUDO EXAMPLE
    438      // A) Init a configuration object
    439      WebPDecoderConfig config;
    440      CHECK(WebPInitDecoderConfig(&config));
    441 
    442      // B) optional: retrieve the bitstream's features.
    443      CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK);
    444 
    445      // C) Adjust 'config' options, if needed
    446      config.options.no_fancy_upsampling = 1;
    447      config.options.use_scaling = 1;
    448      config.options.scaled_width = scaledWidth();
    449      config.options.scaled_height = scaledHeight();
    450      // etc.
    451 
    452      // D) Specify 'config' output options for specifying output colorspace.
    453      // Optionally the external image decode buffer can also be specified.
    454      config.output.colorspace = MODE_BGRA;
    455      // Optionally, the config.output can be pointed to an external buffer as
    456      // well for decoding the image. This externally supplied memory buffer
    457      // should be big enough to store the decoded picture.
    458      config.output.u.RGBA.rgba = (uint8_t*) memory_buffer;
    459      config.output.u.RGBA.stride = scanline_stride;
    460      config.output.u.RGBA.size = total_size_of_the_memory_buffer;
    461      config.output.is_external_memory = 1;
    462 
    463      // E) Decode the WebP image. There are two variants w.r.t decoding image.
    464      // The first one (E.1) decodes the full image and the second one (E.2) is
    465      // used to incrementally decode the image using small input buffers.
    466      // Any one of these steps can be used to decode the WebP image.
    467 
    468      // E.1) Decode full image.
    469      CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK);
    470 
    471      // E.2) Decode image incrementally.
    472      WebPIDecoder* const idec = WebPIDecode(NULL, NULL, &config);
    473      CHECK(idec != NULL);
    474      while (bytes_remaining > 0) {
    475        VP8StatusCode status = WebPIAppend(idec, input, bytes_read);
    476        if (status == VP8_STATUS_OK || status == VP8_STATUS_SUSPENDED) {
    477          bytes_remaining -= bytes_read;
    478        } else {
    479          break;
    480        }
    481      }
    482      WebPIDelete(idec);
    483 
    484      // F) Decoded image is now in config.output (and config.output.u.RGBA).
    485      // It can be saved, displayed or otherwise processed.
    486 
    487      // G) Reclaim memory allocated in config's object. It's safe to call
    488      // this function even if the memory is external and wasn't allocated
    489      // by WebPDecode().
    490      WebPFreeDecBuffer(&config.output);
    491 
    492 -------------------------------------- END PSEUDO EXAMPLE
    493 
    494 Bugs:
    495 =====
    496 
    497 Please report all bugs to our issue tracker:
    498     http://code.google.com/p/webp/issues
    499 Patches welcome! See this page to get started:
    500     http://www.webmproject.org/code/contribute/submitting-patches/
    501 
    502 Discuss:
    503 ========
    504 
    505 Email: webp-discuss (a] webmproject.org
    506 Web: http://groups.google.com/a/webmproject.org/group/webp-discuss
    507 

README.android

      1 URL: http://review.webmproject.org/gitweb?p=libwebp.git
      2 Version: 43/1443/1
      3 License: Google BSD like
      4 
      5 Local modifications:
      6 - Rewrite Android.mk to remove duplicate definitions and set module name
      7   in a consistent way with other external libraries
      8 - Move public headers from src/webp to include/webp, so path to headers
      9   may be appended into CFLAGS without risk for other private headers
     10   (e.g. bits.h) to leak into
     11 - Sync-patch with libwebp ver 0.1.2
     12 - Removed Build files necessary for building via autoconf/automake tools
     13   These files are not required to build via Android.mk
     14   - Makefile.am  Makefile.vc Makefile.in
     15   - config.h.in configure config.guess config.sub configure.ac
     16   - autogen.sh install-sh missing depcomp ltmain.sh aclocal.m4
     17 - Added WebP Encoder (ver 0.1.2) as well
     18   - Removed some more unused Makefile.am & Makefile.in
     19   - Added Android.mk to encoder & decoder code levels.
     20 - Synced the WebP Code (Encoder/Decoder) with the head change#Ia53f845b
     21   - Added three color-spaces viz ARGB_8888, RGBA_4444, RGB_565
     22     supported by Android.
     23 - Fixed the Endian'ness bug for Color-Configs (RGB_565 & ARGB_4444).
     24   The fix is similar to jpeglib handling for JCS_RGB_565 & JCS_RGBA_8888
     25   color configs. Added the code under "ANDROID_WEBP_RGB" flag.
     26 - Sync-patch with libwebp ver 0.2.0-rc1 (head change#Ia5475247).
     27 - Updated WebP with head change#I3da2063b
     28 - Updated WebP with head change#I9e5ae737
     29   - 16bit swapping of RGB565 / RGB4444 colorspace. Added compile-time flag
     30     WEBP_SWAP_16BIT_CSP to support byte-swap (required for skia data type for
     31     16bit values) output for these colorspaces.
     32   - Added ARM/NEON code for decoder/encoder modules.
     33   - Speedup in WebP compression (method 3 and above).
     34   - Added multi-threaded alpha encoding for lossy compression.
     35   - Updated WebP with head change#I9e5ae737
     36 
     37 The Android.mk file creates WebP Decoder and Encoder static libraries which
     38 can be added to any application by Adding to LOCAL_STATIC_LIBRARIES
     39 libwebp-decode libwebp-encode:
     40 
     41   LOCAL_STATIC_LIBRARIES += libwebp-decode libwebp-encode
     42 
     43