src/SDL2/external/libwebp-0.3.0/README

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