1 __ __ ____ ____ ____ 2 / \\/ \/ _ \/ _ )/ _ \ 3 \ / __/ _ \ __/ 4 \__\__/\____/\_____/__/ ____ ___ 5 / _/ / \ \ / _ \/ _/ 6 / \_/ / / \ \ __/ \__ 7 \____/____/\_____/_____/____/v0.2.1 8 9Description: 10============ 11 12WebP codec: library to encode and decode images in WebP format. This package 13contains the library that can be used in other programs to add WebP support, 14as well as the command line tools 'cwebp' and 'dwebp'. 15 16See http://developers.google.com/speed/webp 17 18Latest sources are available from http://www.webmproject.org/code/ 19 20It is released under the same license as the WebM project. 21See http://www.webmproject.org/license/software/ or the 22file "COPYING" file for details. An additional intellectual 23property rights grant can be found in the file PATENTS. 24 25Building: 26========= 27 28Windows build: 29-------------- 30 31By running: 32 33 nmake /f Makefile.vc CFG=release-static RTLIBCFG=static OBJDIR=output 34 35the directory output\release-static\(x64|x86)\bin will contain the tools 36cwebp.exe and dwebp.exe. The directory output\release-static\(x64|x86)\lib will 37contain the libwebp static library. 38The target architecture (x86/x64) is detected by Makefile.vc from the Visual 39Studio compiler (cl.exe) available in the system path. 40 41Unix build using makefile.unix: 42------------------------------- 43 44On platforms with GNU tools installed (gcc and make), running 45 46 make -f makefile.unix 47 48will build the binaries examples/cwebp and examples/dwebp, along 49with the static library src/libwebp.a. No system-wide installation 50is supplied, as this is a simple alternative to the full installation 51system based on the autoconf tools (see below). 52Please refer to the makefile.unix for additional details and customizations. 53 54Using autoconf tools: 55--------------------- 56When building from git sources, you will need to run autogen.sh to generate the 57configure script. 58 59./configure 60make 61make install 62 63should 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 72installed. 73 74Note: The encoding and decoding libraries are compiled separately 75(as src/dec/libwebpdecode.* and src/dec/libwebpencode.*). They 76can be installed independently using a minor modification in the 77corresponding Makefile.am configure files (see comments there). 78 79SWIG bindings: 80-------------- 81 82To 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 85Currently the following functions are mapped: 86Decode: 87 WebPGetDecoderVersion 88 WebPGetInfo 89 WebPDecodeRGBA 90 WebPDecodeARGB 91 WebPDecodeBGRA 92 WebPDecodeBGR 93 WebPDecodeRGB 94 95Encode: 96 WebPGetEncoderVersion 97 WebPEncodeRGBA 98 WebPEncodeBGRA 99 WebPEncodeRGB 100 WebPEncodeBGR 101 WebPEncodeLosslessRGBA 102 WebPEncodeLosslessBGRA 103 WebPEncodeLosslessRGB 104 WebPEncodeLosslessBGR 105 106Java bindings: 107 108To build the swig-generated JNI wrapper code at least JDK-1.5 (or equivalent) 109is necessary for enum support. The output is intended to be a shared object / 110DLL that can be loaded via System.loadLibrary("webp_jni"). 111 112Encoding tool: 113============== 114 115The examples/ directory contains tools for encoding (cwebp) and 116decoding (dwebp) images. 117 118The easiest use should look like: 119 cwebp input.png -q 80 -o output.webp 120which will convert the input file to a WebP file using a quality factor of 80 121on a 0->100 scale (0 being the lowest quality, 100 being the best. Default 122value is 75). 123You 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 125control the amount of processing time spent trying to make the output file as 126small as possible. 127 128A longer list of options is available using the -longhelp command line flag: 129 130> cwebp -longhelp 131Usage: 132 cwebp [-preset <...>] [options] in_file [-o out_file] 133 134If input size (-s) for an image is not specified, it is assumed to be a PNG, 135JPEG or TIFF file. 136options: 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 188Experimental Options: 189 -jpeg_like ............. Roughly match expected JPEG size. 190 -af .................... auto-adjust filter strength. 191 -pre <int> ............. pre-processing filter 192 193 194The main options you might want to try in order to further tune the 195visual quality are: 196 -preset 197 -sns 198 -f 199 -m 200 201Namely: 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 224Decoding tool: 225============== 226 227There is a decoding sample in examples/dwebp.c which will take 228a .webp file and decode it to a PNG image file (amongst other formats). 229This is simply to demonstrate the use of the API. You can verify the 230file 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 236The full list of options is available using -h: 237 238> dwebp -h 239Usage: dwebp in_file [options] [-o out_file] 240 241Decodes the WebP image file to PNG format [Default] 242Use 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 261Visualization tool: 262=================== 263 264There's a little self-serve visualization tool called 'vwebp' under the 265examples/ directory. It uses OpenGL to open a simple drawing window and show 266a decoded WebP file. It's not yet integrated in the automake or makefile.unix 267build system, but you can try to manually compile it using the recommendations 268at the top of the source file. 269 270Usage: 'vwebp my_picture.webp' 271 272 273Encoding API: 274============= 275 276The main encoding functions are available in the header src/webp/encode.h 277The ready-to-use ones are: 278size_t WebPEncodeRGB(const uint8_t* rgb, int width, int height, int stride, 279 float quality_factor, uint8_t** output); 280size_t WebPEncodeBGR(const uint8_t* bgr, int width, int height, int stride, 281 float quality_factor, uint8_t** output); 282size_t WebPEncodeRGBA(const uint8_t* rgba, int width, int height, int stride, 283 float quality_factor, uint8_t** output); 284size_t WebPEncodeBGRA(const uint8_t* bgra, int width, int height, int stride, 285 float quality_factor, uint8_t** output); 286 287They will convert raw RGB samples to a WebP data. The only control supplied 288is the quality factor. 289 290There are some variants for using the lossless format: 291 292size_t WebPEncodeLosslessRGB(const uint8_t* rgb, int width, int height, 293 int stride, uint8_t** output); 294size_t WebPEncodeLosslessBGR(const uint8_t* bgr, int width, int height, 295 int stride, uint8_t** output); 296size_t WebPEncodeLosslessRGBA(const uint8_t* rgba, int width, int height, 297 int stride, uint8_t** output); 298size_t WebPEncodeLosslessBGRA(const uint8_t* bgra, int width, int height, 299 int stride, uint8_t** output); 300 301Of course in this case, no quality factor is needed since the compression 302occurs without loss of the input values, at the expense of larger output sizes. 303 304Advanced encoding API: 305---------------------- 306 307A more advanced API is based on the WebPConfig and WebPPicture structures. 308 309WebPConfig contains the encoding settings and is not tied to a particular 310picture. 311WebPPicture contains input data, on which some WebPConfig will be used for 312compression. 313The 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 362Decoding API: 363============= 364 365This is mainly just one function to call: 366 367#include "webp/decode.h" 368uint8_t* WebPDecodeRGB(const uint8_t* data, size_t data_size, 369 int* width, int* height); 370 371Please have a look at the file src/webp/decode.h for the details. 372There are variants for decoding in BGR/RGBA/ARGB/BGRA order, along with 373decoding to raw Y'CbCr samples. One can also decode the image directly into a 374pre-allocated buffer. 375 376To 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); 379is supplied. No decoding is involved when using it. 380 381Incremental decoding API: 382========================= 383 384In the case when data is being progressively transmitted, pictures can still 385be incrementally decoded using a slightly more complicated API. Decoder state 386is stored into an instance of the WebPIDecoder object. This object can be 387created with the purpose of decoding either RGB or Y'CbCr samples. 388For instance: 389 390 WebPDecBuffer buffer; 391 WebPInitDecBuffer(&buffer); 392 buffer.colorspace = MODE_BGR; 393 ... 394 WebPIDecoder* idec = WebPINewDecoder(&buffer); 395 396As data is made progressively available, this incremental-decoder object 397can be used to decode the picture further. There are two (mutually exclusive) 398ways to pass freshly arrived data: 399 400either by appending the fresh bytes: 401 402 WebPIAppend(idec, fresh_data, size_of_fresh_data); 403 404or by just mentioning the new size of the transmitted data: 405 406 WebPIUpdate(idec, buffer, size_of_transmitted_buffer); 407 408Note that 'buffer' can be modified between each call to WebPIUpdate, in 409particular when the buffer is resized to accommodate larger data. 410 411These functions will return the decoding status: either VP8_STATUS_SUSPENDED if 412decoding is not finished yet or VP8_STATUS_OK when decoding is done. Any other 413status is an error condition. 414 415The 'idec' object must always be released (even upon an error condition) by 416calling: WebPDelete(idec). 417 418To retrieve partially decoded picture samples, one must use the corresponding 419method: WebPIDecGetRGB or WebPIDecGetYUVA. 420It will return the last displayable pixel row. 421 422Lastly, note that decoding can also be performed into a pre-allocated pixel 423buffer. This buffer must be passed when creating a WebPIDecoder, calling 424WebPINewRGB() or WebPINewYUVA(). 425 426Please have a look at the src/webp/decode.h header for further details. 427 428Advanced Decoding API: 429====================== 430 431WebP decoding supports an advanced API which provides on-the-fly cropping and 432rescaling, something of great usefulness on memory-constrained environments like 433mobile phones. Basically, the memory usage will scale with the output's size, 434not the input's, when one only needs a quick preview or a zoomed in portion of 435an 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 494Bugs: 495===== 496 497Please report all bugs to our issue tracker: 498 http://code.google.com/p/webp/issues 499Patches welcome! See this page to get started: 500 http://www.webmproject.org/code/contribute/submitting-patches/ 501 502Discuss: 503======== 504 505Email: webp-discuss@webmproject.org 506Web: http://groups.google.com/a/webmproject.org/group/webp-discuss 507