From 54e61a3864fdbe2f78e24f6f4f5958b53d137427 Mon Sep 17 00:00:00 2001 From: Maryla Date: Mon, 14 Feb 2022 11:19:52 +0000 Subject: [PATCH] Markdownify libwebp docs and reorganize them. Break the main README into into multiple pages in the doc/ directory, except for the tests, swig and webp_js docs which are in the corresponding directories. The webp mux doc is merged into the API doc and the tools doc. Change-Id: Ia407617dd88094f4662841d37947cfef80799914 --- README | 795 --------------------------- README.md | 53 ++ README.mux | 258 --------- README.webp_js | 75 --- doc/README | 29 - doc/api.md | 385 +++++++++++++ doc/building.md | 213 +++++++ doc/specs_generation.md | 26 + doc/tools.md | 512 +++++++++++++++++ doc/webp-container-spec.txt | 4 +- doc/webp-lossless-bitstream-spec.txt | 4 +- swig/{README => README.md} | 31 +- tests/README | 19 - tests/README.md | 18 + webp_js/README.md | 78 +++ 15 files changed, 1310 insertions(+), 1190 deletions(-) delete mode 100644 README create mode 100644 README.md delete mode 100644 README.mux delete mode 100644 README.webp_js delete mode 100644 doc/README create mode 100644 doc/api.md create mode 100644 doc/building.md create mode 100644 doc/specs_generation.md create mode 100644 doc/tools.md rename swig/{README => README.md} (78%) delete mode 100644 tests/README create mode 100644 tests/README.md create mode 100644 webp_js/README.md diff --git a/README b/README deleted file mode 100644 index f6eaf2c0..00000000 --- a/README +++ /dev/null @@ -1,795 +0,0 @@ - __ __ ____ ____ ____ - / \\/ \/ _ \/ _ )/ _ \ - \ / __/ _ \ __/ - \__\__/\____/\_____/__/ ____ ___ - / _/ / \ \ / _ \/ _/ - / \_/ / / \ \ __/ \__ - \____/____/\_____/_____/____/v1.2.2 - -Description: -============ - -WebP codec: library to encode and decode images in WebP format. This package -contains the library that can be used in other programs to add WebP support, -as well as the command line tools 'cwebp' and 'dwebp'. - -See https://developers.google.com/speed/webp - -The latest source tree is available at -https://chromium.googlesource.com/webm/libwebp - -It is released under the same license as the WebM project. -See https://www.webmproject.org/license/software/ or the -"COPYING" file for details. An additional intellectual -property rights grant can be found in the file PATENTS. - -Building: -========= - -Windows build: --------------- - -By running: - - nmake /f Makefile.vc CFG=release-static RTLIBCFG=static OBJDIR=output - -the directory output\release-static\(x64|x86)\bin will contain the tools -cwebp.exe and dwebp.exe. The directory output\release-static\(x64|x86)\lib will -contain the libwebp static library. -The target architecture (x86/x64) is detected by Makefile.vc from the Visual -Studio compiler (cl.exe) available in the system path. - -Unix build using makefile.unix: -------------------------------- - -On platforms with GNU tools installed (gcc and make), running - - make -f makefile.unix - -will build the binaries examples/cwebp and examples/dwebp, along -with the static library src/libwebp.a. No system-wide installation -is supplied, as this is a simple alternative to the full installation -system based on the autoconf tools (see below). -Please refer to makefile.unix for additional details and customizations. - -Using autoconf tools: ---------------------- -Prerequisites: -A compiler (e.g., gcc), make, autoconf, automake, libtool. -On a Debian-like system the following should install everything you need for a -minimal build: -$ sudo apt-get install gcc make autoconf automake libtool - -When building from git sources, you will need to run autogen.sh to generate the -configure script. - -./configure -make -make install - -should be all you need to have the following files - -/usr/local/include/webp/decode.h -/usr/local/include/webp/encode.h -/usr/local/include/webp/types.h -/usr/local/lib/libwebp.* -/usr/local/bin/cwebp -/usr/local/bin/dwebp - -installed. - -Note: A decode-only library, libwebpdecoder, is available using the -'--enable-libwebpdecoder' flag. The encode library is built separately and can -be installed independently using a minor modification in the corresponding -Makefile.am configure files (see comments there). See './configure --help' for -more options. - -Building for MIPS Linux: ------------------------- -MIPS Linux toolchain stable available releases can be found at: -https://community.imgtec.com/developers/mips/tools/codescape-mips-sdk/available-releases/ - -# Add toolchain to PATH -export PATH=$PATH:/path/to/toolchain/bin - -# 32-bit build for mips32r5 (p5600) -HOST=mips-mti-linux-gnu -MIPS_CFLAGS="-O3 -mips32r5 -mabi=32 -mtune=p5600 -mmsa -mfp64 \ - -msched-weight -mload-store-pairs -fPIE" -MIPS_LDFLAGS="-mips32r5 -mabi=32 -mmsa -mfp64 -pie" - -# 64-bit build for mips64r6 (i6400) -HOST=mips-img-linux-gnu -MIPS_CFLAGS="-O3 -mips64r6 -mabi=64 -mtune=i6400 -mmsa -mfp64 \ - -msched-weight -mload-store-pairs -fPIE" -MIPS_LDFLAGS="-mips64r6 -mabi=64 -mmsa -mfp64 -pie" - -./configure --host=${HOST} --build=`config.guess` \ - CC="${HOST}-gcc -EL" \ - CFLAGS="$MIPS_CFLAGS" \ - LDFLAGS="$MIPS_LDFLAGS" -make -make install - -CMake: ------- -With CMake, you can compile libwebp, cwebp, dwebp, gif2webp, img2webp, webpinfo -and the JS bindings. - -Prerequisites: -A compiler (e.g., gcc with autotools) and CMake. -On a Debian-like system the following should install everything you need for a -minimal build: -$ sudo apt-get install build-essential cmake - -When building from git sources, you will need to run cmake to generate the -makefiles. - -mkdir build && cd build && cmake ../ -make -make install - -If you also want any of the executables, you will need to enable them through -CMake, e.g.: - -cmake -DWEBP_BUILD_CWEBP=ON -DWEBP_BUILD_DWEBP=ON ../ - -or through your favorite interface (like ccmake or cmake-qt-gui). - -Use option -DWEBP_UNICODE=ON for Unicode support on Windows (with chcp 65001). - -Finally, once installed, you can also use WebP in your CMake project by doing: - -find_package(WebP) - -which will define the CMake variables WebP_INCLUDE_DIRS and WebP_LIBRARIES. - -Gradle: -------- -The support for Gradle is minimal: it only helps you compile libwebp, cwebp and -dwebp and webpmux_example. - -Prerequisites: -A compiler (e.g., gcc with autotools) and gradle. -On a Debian-like system the following should install everything you need for a -minimal build: -$ sudo apt-get install build-essential gradle - -When building from git sources, you will need to run the Gradle wrapper with the -appropriate target, e.g. : - -./gradlew buildAllExecutables - -SWIG bindings: --------------- - -To generate language bindings from swig/libwebp.swig at least swig-1.3 -(http://www.swig.org) is required. - -Currently the following functions are mapped: -Decode: - WebPGetDecoderVersion - WebPGetInfo - WebPDecodeRGBA - WebPDecodeARGB - WebPDecodeBGRA - WebPDecodeBGR - WebPDecodeRGB - -Encode: - WebPGetEncoderVersion - WebPEncodeRGBA - WebPEncodeBGRA - WebPEncodeRGB - WebPEncodeBGR - WebPEncodeLosslessRGBA - WebPEncodeLosslessBGRA - WebPEncodeLosslessRGB - WebPEncodeLosslessBGR - -See swig/README for more detailed build instructions. - -Java bindings: - -To build the swig-generated JNI wrapper code at least JDK-1.5 (or equivalent) -is necessary for enum support. The output is intended to be a shared object / -DLL that can be loaded via System.loadLibrary("webp_jni"). - -Python bindings: - -To build the swig-generated Python extension code at least Python 2.6 is -required. Python < 2.6 may build with some minor changes to libwebp.swig or the -generated code, but is untested. - -Encoding tool: -============== - -The examples/ directory contains tools for encoding (cwebp) and -decoding (dwebp) images. - -The easiest use should look like: - cwebp input.png -q 80 -o output.webp -which will convert the input file to a WebP file using a quality factor of 80 -on a 0->100 scale (0 being the lowest quality, 100 being the best. Default -value is 75). -You might want to try the -lossless flag too, which will compress the source -(in RGBA format) without any loss. The -q quality parameter will in this case -control the amount of processing time spent trying to make the output file as -small as possible. - -A longer list of options is available using the -longhelp command line flag: - -> cwebp -longhelp -Usage: - cwebp [-preset <...>] [options] in_file [-o out_file] - -If input size (-s) for an image is not specified, it is -assumed to be a PNG, JPEG, TIFF or WebP file. -Note: Animated PNG and WebP files are not supported. - -Options: - -h / -help ............. short help - -H / -longhelp ......... long help - -q ............. quality factor (0:small..100:big), default=75 - -alpha_q ......... transparency-compression quality (0..100), - default=100 - -preset ....... preset setting, one of: - default, photo, picture, - drawing, icon, text - -preset must come first, as it overwrites other parameters - -z ............... activates lossless preset with given - level in [0:fast, ..., 9:slowest] - - -m ............... compression method (0=fast, 6=slowest), default=4 - -segments ........ number of segments to use (1..4), default=4 - -size ............ target size (in bytes) - -psnr .......... target PSNR (in dB. typically: 42) - - -s ......... input size (width x height) for YUV - -sns ............. spatial noise shaping (0:off, 100:max), default=50 - -f ............... filter strength (0=off..100), default=60 - -sharpness ....... filter sharpness (0:most .. 7:least sharp), default=0 - -strong ................ use strong filter instead of simple (default) - -nostrong .............. use simple filter instead of strong - -sharp_yuv ............. use sharper (and slower) RGB->YUV conversion - -partition_limit . limit quality to fit the 512k limit on - the first partition (0=no degradation ... 100=full) - -pass ............ analysis pass number (1..10) - -qrange .... specifies the permissible quality range - (default: 0 100) - -crop .. crop picture with the given rectangle - -resize ........ resize picture (after any cropping) - -mt .................... use multi-threading if available - -low_memory ............ reduce memory usage (slower encoding) - -map ............. print map of extra info - -print_psnr ............ prints averaged PSNR distortion - -print_ssim ............ prints averaged SSIM distortion - -print_lsim ............ prints local-similarity distortion - -d .......... dump the compressed output (PGM file) - -alpha_method .... transparency-compression method (0..1), default=1 - -alpha_filter . predictive filtering for alpha plane, - one of: none, fast (default) or best - -exact ................. preserve RGB values in transparent area, default=off - -blend_alpha ..... blend colors against background color - expressed as RGB values written in - hexadecimal, e.g. 0xc0e0d0 for red=0xc0 - green=0xe0 and blue=0xd0 - -noalpha ............... discard any transparency information - -lossless .............. encode image losslessly, default=off - -near_lossless ... use near-lossless image - preprocessing (0..100=off), default=100 - -hint ......... specify image characteristics hint, - one of: photo, picture or graph - - -metadata ..... comma separated list of metadata to - copy from the input to the output if present. - Valid values: all, none (default), exif, icc, xmp - - -short ................. condense printed message - -quiet ................. don't print anything - -version ............... print version number and exit - -noasm ................. disable all assembly optimizations - -v ..................... verbose, e.g. print encoding/decoding times - -progress .............. report encoding progress - -Experimental Options: - -jpeg_like ............. roughly match expected JPEG size - -af .................... auto-adjust filter strength - -pre ............. pre-processing filter - - -The main options you might want to try in order to further tune the -visual quality are: - -preset - -sns - -f - -m - -Namely: - * 'preset' will set up a default encoding configuration targeting a - particular type of input. It should appear first in the list of options, - so that subsequent options can take effect on top of this preset. - Default value is 'default'. - * 'sns' will progressively turn on (when going from 0 to 100) some additional - visual optimizations (like: segmentation map re-enforcement). This option - will balance the bit allocation differently. It tries to take bits from the - "easy" parts of the picture and use them in the "difficult" ones instead. - Usually, raising the sns value (at fixed -q value) leads to larger files, - but with better quality. - Typical value is around '75'. - * 'f' option directly links to the filtering strength used by the codec's - in-loop processing. The higher the value, the smoother the - highly-compressed area will look. This is particularly useful when aiming - at very small files. Typical values are around 20-30. Note that using the - option -strong/-nostrong will change the type of filtering. Use "-f 0" to - turn filtering off. - * 'm' controls the trade-off between encoding speed and quality. Default is 4. - You can try -m 5 or -m 6 to explore more (time-consuming) encoding - possibilities. A lower value will result in faster encoding at the expense - of quality. - -Decoding tool: -============== - -There is a decoding sample in examples/dwebp.c which will take -a .webp file and decode it to a PNG image file (amongst other formats). -This is simply to demonstrate the use of the API. You can verify the -file test.webp decodes to exactly the same as test_ref.ppm by using: - - cd examples - ./dwebp test.webp -ppm -o test.ppm - diff test.ppm test_ref.ppm - -The full list of options is available using -h: - -> dwebp -h -Usage: dwebp in_file [options] [-o out_file] - -Decodes the WebP image file to PNG format [Default]. -Note: Animated WebP files are not supported. - -Use following options to convert into alternate image formats: - -pam ......... save the raw RGBA samples as a color PAM - -ppm ......... save the raw RGB samples as a color PPM - -bmp ......... save as uncompressed BMP format - -tiff ........ save as uncompressed TIFF format - -pgm ......... save the raw YUV samples as a grayscale PGM - file with IMC4 layout - -yuv ......... save the raw YUV samples in flat layout - - Other options are: - -version ..... print version number and exit - -nofancy ..... don't use the fancy YUV420 upscaler - -nofilter .... disable in-loop filtering - -nodither .... disable dithering - -dither .. dithering strength (in 0..100) - -alpha_dither use alpha-plane dithering if needed - -mt .......... use multi-threading - -crop ... crop output with the given rectangle - -resize ......... scale the output (*after* any cropping) - -flip ........ flip the output vertically - -alpha ....... only save the alpha plane - -incremental . use incremental decoding (useful for tests) - -h ........... this help message - -v ........... verbose (e.g. print encoding/decoding times) - -quiet ....... quiet mode, don't print anything - -noasm ....... disable all assembly optimizations - -WebP file analysis tool: -======================== - -'webpinfo' can be used to print out the chunk level structure and bitstream -header information of WebP files. It can also check if the files are of valid -WebP format. - -Usage: webpinfo [options] in_files -Note: there could be multiple input files; - options must come before input files. -Options: - -version ........... Print version number and exit. - -quiet ............. Do not show chunk parsing information. - -diag .............. Show parsing error diagnosis. - -summary ........... Show chunk stats summary. - -bitstream_info .... Parse bitstream header. - -Visualization tool: -=================== - -There's a little self-serve visualization tool called 'vwebp' under the -examples/ directory. It uses OpenGL to open a simple drawing window and show -a decoded WebP file. It's not yet integrated in the automake build system, but -you can try to manually compile it using the recommendations below. - -Usage: vwebp in_file [options] - -Decodes the WebP image file and visualize it using OpenGL -Options are: - -version ..... print version number and exit - -noicc ....... don't use the icc profile if present - -nofancy ..... don't use the fancy YUV420 upscaler - -nofilter .... disable in-loop filtering - -dither dithering strength (0..100), default=50 - -noalphadither disable alpha plane dithering - -usebgcolor .. display background color - -mt .......... use multi-threading - -info ........ print info - -h ........... this help message - -Keyboard shortcuts: - 'c' ................ toggle use of color profile - 'b' ................ toggle background color display - 'i' ................ overlay file information - 'd' ................ disable blending & disposal (debug) - 'q' / 'Q' / ESC .... quit - -Building: ---------- - -Prerequisites: -1) OpenGL & OpenGL Utility Toolkit (GLUT) - Linux: - $ sudo apt-get install freeglut3-dev mesa-common-dev - Mac + Xcode: - - These libraries should be available in the OpenGL / GLUT frameworks. - Windows: - http://freeglut.sourceforge.net/index.php#download - -2) (Optional) qcms (Quick Color Management System) - i. Download qcms from Mozilla / Chromium: - https://hg.mozilla.org/mozilla-central/file/0e7639e3bdfb/gfx/qcms - https://source.chromium.org/chromium/chromium/src/+/main:third_party/qcms/;drc=d4a2f8e1ed461d8fc05ed88d1ae2dc94c9773825 - ii. Build and archive the source files as libqcms.a / qcms.lib - iii. Update makefile.unix / Makefile.vc - a) Define WEBP_HAVE_QCMS - b) Update include / library paths to reference the qcms directory. - -Build using makefile.unix / Makefile.vc: -$ make -f makefile.unix examples/vwebp -> nmake /f Makefile.vc CFG=release-static \ - ../obj/x64/release-static/bin/vwebp.exe - -Animation creation tool: -======================== -The utility 'img2webp' can turn a sequence of input images (PNG, JPEG, ...) -into an animated WebP file. It offers fine control over duration, encoding -modes, etc. - -Usage: - - img2webp [file_options] [[frame_options] frame_file]... - -File-level options (only used at the start of compression): - -min_size ............ minimize size - -loop .......... loop count (default: 0, = infinite loop) - -kmax .......... maximum number of frame between key-frames - (0=only keyframes) - -kmin .......... minimum number of frame between key-frames - (0=disable key-frames altogether) - -mixed ............... use mixed lossy/lossless automatic mode - -v ................... verbose mode - -h ................... this help - -version ............. print version number and exit - -Per-frame options (only used for subsequent images input): - -d ............. frame duration in ms (default: 100) - -lossless ........... use lossless mode (default) - -lossy ... ........... use lossy mode - -q ........... quality - -m ............. method to use - -example: img2webp -loop 2 in0.png -lossy in1.jpg - -d 80 in2.tiff -o out.webp - -Note: if a single file name is passed as the argument, the arguments will be -tokenized from this file. The file name must not start with the character '-'. - -Animated GIF conversion: -======================== -Animated GIF files can be converted to WebP files with animation using the -gif2webp utility available under examples/. The files can then be viewed using -vwebp. - -Usage: - gif2webp [options] gif_file -o webp_file -Options: - -h / -help ............. this help - -lossy ................. encode image using lossy compression - -mixed ................. for each frame in the image, pick lossy - or lossless compression heuristically - -q ............. quality factor (0:small..100:big) - -m ............... compression method (0=fast, 6=slowest) - -min_size .............. minimize output size (default:off) - lossless compression by default; can be - combined with -q, -m, -lossy or -mixed - options - -kmin ............ min distance between key frames - -kmax ............ max distance between key frames - -f ............... filter strength (0=off..100) - -metadata ..... comma separated list of metadata to - copy from the input to the output if present - Valid values: all, none, icc, xmp (default) - -loop_compatibility .... use compatibility mode for Chrome - version prior to M62 (inclusive) - -mt .................... use multi-threading if available - - -version ............... print version number and exit - -v ..................... verbose - -quiet ................. don't print anything - -Building: ---------- -With the libgif development files installed, gif2webp can be built using -makefile.unix: -$ make -f makefile.unix examples/gif2webp - -or using autoconf: -$ ./configure --enable-everything -$ make - -Comparison of animated images: -============================== -Test utility anim_diff under examples/ can be used to compare two animated -images (each can be GIF or WebP). - -Usage: anim_diff [options] - -Options: - -dump_frames dump decoded frames in PAM format - -min_psnr ... minimum per-frame PSNR - -raw_comparison ..... if this flag is not used, RGB is - premultiplied before comparison - -max_diff ..... maximum allowed difference per channel - between corresponding pixels in subsequent - frames - -h .................. this help - -version ............ print version number and exit - -Building: ---------- -With the libgif development files and a C++ compiler installed, anim_diff can -be built using makefile.unix: -$ make -f makefile.unix examples/anim_diff - -or using autoconf: -$ ./configure --enable-everything -$ make - -Encoding API: -============= - -The main encoding functions are available in the header src/webp/encode.h -The ready-to-use ones are: -size_t WebPEncodeRGB(const uint8_t* rgb, int width, int height, int stride, - float quality_factor, uint8_t** output); -size_t WebPEncodeBGR(const uint8_t* bgr, int width, int height, int stride, - float quality_factor, uint8_t** output); -size_t WebPEncodeRGBA(const uint8_t* rgba, int width, int height, int stride, - float quality_factor, uint8_t** output); -size_t WebPEncodeBGRA(const uint8_t* bgra, int width, int height, int stride, - float quality_factor, uint8_t** output); - -They will convert raw RGB samples to a WebP data. The only control supplied -is the quality factor. - -There are some variants for using the lossless format: - -size_t WebPEncodeLosslessRGB(const uint8_t* rgb, int width, int height, - int stride, uint8_t** output); -size_t WebPEncodeLosslessBGR(const uint8_t* bgr, int width, int height, - int stride, uint8_t** output); -size_t WebPEncodeLosslessRGBA(const uint8_t* rgba, int width, int height, - int stride, uint8_t** output); -size_t WebPEncodeLosslessBGRA(const uint8_t* bgra, int width, int height, - int stride, uint8_t** output); - -Of course in this case, no quality factor is needed since the compression -occurs without loss of the input values, at the expense of larger output sizes. - -Advanced encoding API: ----------------------- - -A more advanced API is based on the WebPConfig and WebPPicture structures. - -WebPConfig contains the encoding settings and is not tied to a particular -picture. -WebPPicture contains input data, on which some WebPConfig will be used for -compression. -The encoding flow looks like: - --------------------------------------- BEGIN PSEUDO EXAMPLE - -#include - - // Setup a config, starting form a preset and tuning some additional - // parameters - WebPConfig config; - if (!WebPConfigPreset(&config, WEBP_PRESET_PHOTO, quality_factor)) { - return 0; // version error - } - // ... additional tuning - config.sns_strength = 90; - config.filter_sharpness = 6; - config_error = WebPValidateConfig(&config); // not mandatory, but useful - - // Setup the input data - WebPPicture pic; - if (!WebPPictureInit(&pic)) { - return 0; // version error - } - pic.width = width; - pic.height = height; - // allocated picture of dimension width x height - if (!WebPPictureAlloc(&pic)) { - return 0; // memory error - } - // at this point, 'pic' has been initialized as a container, - // and can receive the Y/U/V samples. - // Alternatively, one could use ready-made import functions like - // WebPPictureImportRGB(), which will take care of memory allocation. - // In any case, past this point, one will have to call - // WebPPictureFree(&pic) to reclaim memory. - - // Set up a byte-output write method. WebPMemoryWriter, for instance. - WebPMemoryWriter wrt; - WebPMemoryWriterInit(&wrt); // initialize 'wrt' - - pic.writer = MyFileWriter; - pic.custom_ptr = my_opaque_structure_to_make_MyFileWriter_work; - - // Compress! - int ok = WebPEncode(&config, &pic); // ok = 0 => error occurred! - WebPPictureFree(&pic); // must be called independently of the 'ok' result. - - // output data should have been handled by the writer at that point. - // -> compressed data is the memory buffer described by wrt.mem / wrt.size - - // deallocate the memory used by compressed data - WebPMemoryWriterClear(&wrt); - --------------------------------------- END PSEUDO EXAMPLE - -Decoding API: -============= - -This is mainly just one function to call: - -#include "webp/decode.h" -uint8_t* WebPDecodeRGB(const uint8_t* data, size_t data_size, - int* width, int* height); - -Please have a look at the file src/webp/decode.h for the details. -There are variants for decoding in BGR/RGBA/ARGB/BGRA order, along with -decoding to raw Y'CbCr samples. One can also decode the image directly into a -pre-allocated buffer. - -To detect a WebP file and gather the picture's dimensions, the function: - int WebPGetInfo(const uint8_t* data, size_t data_size, - int* width, int* height); -is supplied. No decoding is involved when using it. - -Incremental decoding API: -========================= - -In the case when data is being progressively transmitted, pictures can still -be incrementally decoded using a slightly more complicated API. Decoder state -is stored into an instance of the WebPIDecoder object. This object can be -created with the purpose of decoding either RGB or Y'CbCr samples. -For instance: - - WebPDecBuffer buffer; - WebPInitDecBuffer(&buffer); - buffer.colorspace = MODE_BGR; - ... - WebPIDecoder* idec = WebPINewDecoder(&buffer); - -As data is made progressively available, this incremental-decoder object -can be used to decode the picture further. There are two (mutually exclusive) -ways to pass freshly arrived data: - -either by appending the fresh bytes: - - WebPIAppend(idec, fresh_data, size_of_fresh_data); - -or by just mentioning the new size of the transmitted data: - - WebPIUpdate(idec, buffer, size_of_transmitted_buffer); - -Note that 'buffer' can be modified between each call to WebPIUpdate, in -particular when the buffer is resized to accommodate larger data. - -These functions will return the decoding status: either VP8_STATUS_SUSPENDED if -decoding is not finished yet or VP8_STATUS_OK when decoding is done. Any other -status is an error condition. - -The 'idec' object must always be released (even upon an error condition) by -calling: WebPDelete(idec). - -To retrieve partially decoded picture samples, one must use the corresponding -method: WebPIDecGetRGB or WebPIDecGetYUVA. -It will return the last displayable pixel row. - -Lastly, note that decoding can also be performed into a pre-allocated pixel -buffer. This buffer must be passed when creating a WebPIDecoder, calling -WebPINewRGB() or WebPINewYUVA(). - -Please have a look at the src/webp/decode.h header for further details. - -Advanced Decoding API: -====================== - -WebP decoding supports an advanced API which provides on-the-fly cropping and -rescaling, something of great usefulness on memory-constrained environments like -mobile phones. Basically, the memory usage will scale with the output's size, -not the input's, when one only needs a quick preview or a zoomed in portion of -an otherwise too-large picture. Some CPU can be saved too, incidentally. - --------------------------------------- BEGIN PSEUDO EXAMPLE - // A) Init a configuration object - WebPDecoderConfig config; - CHECK(WebPInitDecoderConfig(&config)); - - // B) optional: retrieve the bitstream's features. - CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK); - - // C) Adjust 'config' options, if needed - config.options.no_fancy_upsampling = 1; - config.options.use_scaling = 1; - config.options.scaled_width = scaledWidth(); - config.options.scaled_height = scaledHeight(); - // etc. - - // D) Specify 'config' output options for specifying output colorspace. - // Optionally the external image decode buffer can also be specified. - config.output.colorspace = MODE_BGRA; - // Optionally, the config.output can be pointed to an external buffer as - // well for decoding the image. This externally supplied memory buffer - // should be big enough to store the decoded picture. - config.output.u.RGBA.rgba = (uint8_t*) memory_buffer; - config.output.u.RGBA.stride = scanline_stride; - config.output.u.RGBA.size = total_size_of_the_memory_buffer; - config.output.is_external_memory = 1; - - // E) Decode the WebP image. There are two variants w.r.t decoding image. - // The first one (E.1) decodes the full image and the second one (E.2) is - // used to incrementally decode the image using small input buffers. - // Any one of these steps can be used to decode the WebP image. - - // E.1) Decode full image. - CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK); - - // E.2) Decode image incrementally. - WebPIDecoder* const idec = WebPIDecode(NULL, NULL, &config); - CHECK(idec != NULL); - while (bytes_remaining > 0) { - VP8StatusCode status = WebPIAppend(idec, input, bytes_read); - if (status == VP8_STATUS_OK || status == VP8_STATUS_SUSPENDED) { - bytes_remaining -= bytes_read; - } else { - break; - } - } - WebPIDelete(idec); - - // F) Decoded image is now in config.output (and config.output.u.RGBA). - // It can be saved, displayed or otherwise processed. - - // G) Reclaim memory allocated in config's object. It's safe to call - // this function even if the memory is external and wasn't allocated - // by WebPDecode(). - WebPFreeDecBuffer(&config.output); - --------------------------------------- END PSEUDO EXAMPLE - -Bugs: -===== - -Please report all bugs to the issue tracker: - https://bugs.chromium.org/p/webp -Patches welcome! See this page to get started: - https://www.webmproject.org/code/contribute/submitting-patches/ - -Discuss: -======== - -Email: webp-discuss@webmproject.org -Web: https://groups.google.com/a/webmproject.org/group/webp-discuss diff --git a/README.md b/README.md new file mode 100644 index 00000000..a20ddff0 --- /dev/null +++ b/README.md @@ -0,0 +1,53 @@ +# WebP Codec + +``` + __ __ ____ ____ ____ + / \\/ \/ _ \/ _ )/ _ \ + \ / __/ _ \ __/ + \__\__/\____/\_____/__/ ____ ___ + / _/ / \ \ / _ \/ _/ + / \_/ / / \ \ __/ \__ + \____/____/\_____/_____/____/v1.2.2 +``` + +WebP codec is a library to encode and decode images in WebP format. This package +contains the library that can be used in other programs to add WebP support, as +well as the command line tools 'cwebp' and 'dwebp' to compress and decompress +images respectively. + +See https://developers.google.com/speed/webp for details on the image format. + +The latest source tree is available at +https://chromium.googlesource.com/webm/libwebp + +It is released under the same license as the WebM project. See +https://www.webmproject.org/license/software/ or the "COPYING" file for details. +An additional intellectual property rights grant can be found in the file +PATENTS. + +## Building + +See the [building documentation](doc/building.md). + +## Encoding and Decoding Tools + +The examples/ directory contains tools to encode and decode images and +animations, view information about WebP images, and more. See the +[tools documentation](doc/tools.md). + +## APIs + +See the [APIs documentation](doc/api.md), and API usage examples in the +`examples/` directory. + +## Bugs + +Please report all bugs to the issue tracker: https://bugs.chromium.org/p/webp + +Patches welcome! See [how to contribute](CONTRIBUTING.md). + +## Discuss + +Email: webp-discuss@webmproject.org + +Web: https://groups.google.com/a/webmproject.org/group/webp-discuss diff --git a/README.mux b/README.mux deleted file mode 100644 index 099d8e06..00000000 --- a/README.mux +++ /dev/null @@ -1,258 +0,0 @@ - __ __ ____ ____ ____ __ __ _ __ __ - / \\/ \/ _ \/ _ \/ _ \/ \ \/ \___/_ / _\ - \ / __/ _ \ __/ / / (_/ /__ - \__\__/\_____/_____/__/ \__//_/\_____/__/___/v1.2.2 - - -Description: -============ - -WebPMux: set of two libraries 'Mux' and 'Demux' for creation, extraction and -manipulation of an extended format WebP file, which can have features like -color profile, metadata and animation. Reference command-line tools 'webpmux' -and 'vwebp' as well as the WebP container specification -'doc/webp-container-spec.txt' are also provided in this package. - -WebP Mux tool: -============== - -The examples/ directory contains a tool (webpmux) for manipulating WebP -files. The webpmux tool can be used to create an extended format WebP file and -also to extract or strip relevant data from such a file. - -A list of options is available using the -help command line flag: - -> webpmux -help -Usage: webpmux -get GET_OPTIONS INPUT -o OUTPUT - webpmux -set SET_OPTIONS INPUT -o OUTPUT - webpmux -duration DURATION_OPTIONS [-duration ...] - INPUT -o OUTPUT - webpmux -strip STRIP_OPTIONS INPUT -o OUTPUT - webpmux -frame FRAME_OPTIONS [-frame...] [-loop LOOP_COUNT] - [-bgcolor BACKGROUND_COLOR] -o OUTPUT - webpmux -info INPUT - webpmux [-h|-help] - webpmux -version - webpmux argument_file_name - -GET_OPTIONS: - Extract relevant data: - icc get ICC profile - exif get EXIF metadata - xmp get XMP metadata - frame n get nth frame - -SET_OPTIONS: - Set color profile/metadata/parameters: - loop LOOP_COUNT set the loop count - bgcolor BACKGROUND_COLOR set the animation background color - icc file.icc set ICC profile - exif file.exif set EXIF metadata - xmp file.xmp set XMP metadata - where: 'file.icc' contains the ICC profile to be set, - 'file.exif' contains the EXIF metadata to be set - 'file.xmp' contains the XMP metadata to be set - -DURATION_OPTIONS: - Set duration of selected frames: - duration set duration for each frames - duration,frame set duration of a particular frame - duration,start,end set duration of frames in the - interval [start,end]) - where: 'duration' is the duration in milliseconds - 'start' is the start frame index - 'end' is the inclusive end frame index - The special 'end' value '0' means: last frame. - -STRIP_OPTIONS: - Strip color profile/metadata: - icc strip ICC profile - exif strip EXIF metadata - xmp strip XMP metadata - -FRAME_OPTIONS(i): - Create animation: - file_i +di+[xi+yi[+mi[bi]]] - where: 'file_i' is the i'th animation frame (WebP format), - 'di' is the pause duration before next frame, - 'xi','yi' specify the image offset for this frame, - 'mi' is the dispose method for this frame (0 or 1), - 'bi' is the blending method for this frame (+b or -b) - -LOOP_COUNT: - Number of times to repeat the animation. - Valid range is 0 to 65535 [Default: 0 (infinite)]. - -BACKGROUND_COLOR: - Background color of the canvas. - A,R,G,B - where: 'A', 'R', 'G' and 'B' are integers in the range 0 to 255 specifying - the Alpha, Red, Green and Blue component values respectively - [Default: 255,255,255,255] - -INPUT & OUTPUT are in WebP format. - -Note: The nature of EXIF, XMP and ICC data is not checked and is assumed to be -valid. - -Note: if a single file name is passed as the argument, the arguments will be -tokenized from this file. The file name must not start with the character '-'. - -Visualization tool: -=================== - -The examples/ directory also contains a tool (vwebp) for viewing WebP files. -It decodes the image and visualizes it using OpenGL. See the libwebp README -for details on building and running this program. - -Mux API: -======== -The Mux API contains methods for adding data to and reading data from WebP -files. This API currently supports XMP/EXIF metadata, ICC profile and animation. -Other features may be added in subsequent releases. - -Example#1 (pseudo code): Creating a WebPMux object with image data, color -profile and XMP metadata. - - int copy_data = 0; - WebPMux* mux = WebPMuxNew(); - // ... (Prepare image data). - WebPMuxSetImage(mux, &image, copy_data); - // ... (Prepare ICC profile data). - WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data); - // ... (Prepare XMP metadata). - WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data); - // Get data from mux in WebP RIFF format. - WebPMuxAssemble(mux, &output_data); - WebPMuxDelete(mux); - // ... (Consume output_data; e.g. write output_data.bytes to file). - WebPDataClear(&output_data); - - -Example#2 (pseudo code): Get image and color profile data from a WebP file. - - int copy_data = 0; - // ... (Read data from file). - WebPMux* mux = WebPMuxCreate(&data, copy_data); - WebPMuxGetFrame(mux, 1, &image); - // ... (Consume image; e.g. call WebPDecode() to decode the data). - WebPMuxGetChunk(mux, "ICCP", &icc_profile); - // ... (Consume icc_profile). - WebPMuxDelete(mux); - free(data); - - -For a detailed Mux API reference, please refer to the header file -(src/webp/mux.h). - -Demux API: -========== -The Demux API enables extraction of images and extended format data from -WebP files. This API currently supports reading of XMP/EXIF metadata, ICC -profile and animated images. Other features may be added in subsequent -releases. - -Code example: Demuxing WebP data to extract all the frames, ICC profile -and EXIF/XMP metadata. - - WebPDemuxer* demux = WebPDemux(&webp_data); - uint32_t width = WebPDemuxGetI(demux, WEBP_FF_CANVAS_WIDTH); - uint32_t height = WebPDemuxGetI(demux, WEBP_FF_CANVAS_HEIGHT); - // ... (Get information about the features present in the WebP file). - uint32_t flags = WebPDemuxGetI(demux, WEBP_FF_FORMAT_FLAGS); - - // ... (Iterate over all frames). - WebPIterator iter; - if (WebPDemuxGetFrame(demux, 1, &iter)) { - do { - // ... (Consume 'iter'; e.g. Decode 'iter.fragment' with WebPDecode(), - // ... and get other frame properties like width, height, offsets etc. - // ... see 'struct WebPIterator' below for more info). - } while (WebPDemuxNextFrame(&iter)); - WebPDemuxReleaseIterator(&iter); - } - - // ... (Extract metadata). - WebPChunkIterator chunk_iter; - if (flags & ICCP_FLAG) WebPDemuxGetChunk(demux, "ICCP", 1, &chunk_iter); - // ... (Consume the ICC profile in 'chunk_iter.chunk'). - WebPDemuxReleaseChunkIterator(&chunk_iter); - if (flags & EXIF_FLAG) WebPDemuxGetChunk(demux, "EXIF", 1, &chunk_iter); - // ... (Consume the EXIF metadata in 'chunk_iter.chunk'). - WebPDemuxReleaseChunkIterator(&chunk_iter); - if (flags & XMP_FLAG) WebPDemuxGetChunk(demux, "XMP ", 1, &chunk_iter); - // ... (Consume the XMP metadata in 'chunk_iter.chunk'). - WebPDemuxReleaseChunkIterator(&chunk_iter); - WebPDemuxDelete(demux); - - -For a detailed Demux API reference, please refer to the header file -(src/webp/demux.h). - -AnimEncoder API: -================ -The AnimEncoder API can be used to create animated WebP images. - -Code example: - - WebPAnimEncoderOptions enc_options; - WebPAnimEncoderOptionsInit(&enc_options); - // ... (Tune 'enc_options' as needed). - WebPAnimEncoder* enc = WebPAnimEncoderNew(width, height, &enc_options); - while() { - WebPConfig config; - WebPConfigInit(&config); - // ... (Tune 'config' as needed). - WebPAnimEncoderAdd(enc, frame, duration, &config); - } - WebPAnimEncoderAssemble(enc, webp_data); - WebPAnimEncoderDelete(enc); - // ... (Write the 'webp_data' to a file, or re-mux it further). - - -For a detailed AnimEncoder API reference, please refer to the header file -(src/webp/mux.h). - -AnimDecoder API: -================ -This AnimDecoder API allows decoding (possibly) animated WebP images. - -Code Example: - - WebPAnimDecoderOptions dec_options; - WebPAnimDecoderOptionsInit(&dec_options); - // Tune 'dec_options' as needed. - WebPAnimDecoder* dec = WebPAnimDecoderNew(webp_data, &dec_options); - WebPAnimInfo anim_info; - WebPAnimDecoderGetInfo(dec, &anim_info); - for (uint32_t i = 0; i < anim_info.loop_count; ++i) { - while (WebPAnimDecoderHasMoreFrames(dec)) { - uint8_t* buf; - int timestamp; - WebPAnimDecoderGetNext(dec, &buf, ×tamp); - // ... (Render 'buf' based on 'timestamp'). - // ... (Do NOT free 'buf', as it is owned by 'dec'). - } - WebPAnimDecoderReset(dec); - } - const WebPDemuxer* demuxer = WebPAnimDecoderGetDemuxer(dec); - // ... (Do something using 'demuxer'; e.g. get EXIF/XMP/ICC data). - WebPAnimDecoderDelete(dec); - -For a detailed AnimDecoder API reference, please refer to the header file -(src/webp/demux.h). - - -Bugs: -===== - -Please report all bugs to the issue tracker: - https://bugs.chromium.org/p/webp -Patches welcome! See this page to get started: - https://www.webmproject.org/code/contribute/submitting-patches/ - -Discuss: -======== - -Email: webp-discuss@webmproject.org -Web: https://groups.google.com/a/webmproject.org/group/webp-discuss diff --git a/README.webp_js b/README.webp_js deleted file mode 100644 index 3d453a20..00000000 --- a/README.webp_js +++ /dev/null @@ -1,75 +0,0 @@ - __ __ ____ ____ ____ __ ____ - / \\/ \ _ \ _ \ _ \ (__)/ __\ - \ / __/ _ \ __/ _) \_ \ - \__\__/_____/____/_/ /____/____/ - -Description: -============ - -This file describes the compilation of libwebp into a JavaScript decoder -using Emscripten and CMake. - - - install the Emscripten SDK following the procedure described at: - https://emscripten.org/docs/getting_started/downloads.html#installation-instructions-using-the-emsdk-recommended - After installation, you should have some global variable positioned to the - location of the SDK. In particular, $EMSDK should point to the - top-level directory containing Emscripten tools. - - - configure the project 'WEBP_JS' with CMake using: - - cd webp_js && \ - emcmake cmake -DWEBP_BUILD_WEBP_JS=ON \ - ../ - - - compile webp.js using 'emmake make'. - - - that's it! Upon completion, you should have the webp.js and - webp.wasm files generated. - -The callable JavaScript function is WebPToSDL(), which decodes a raw WebP -bitstream into a canvas. See webp_js/index.html for a simple usage sample -(see below for instructions). - -Demo HTML page: -=============== - - The HTML page webp_js/index.html requires an HTTP server to serve the WebP - image example. It's easy to just use Python for that. - -cd webp_js && python -m SimpleHTTPServer 8080 - -and then navigate to http://localhost:8080 in your favorite browser. - - -Web-Assembly (WASM) version: -============================ - - CMakeLists.txt is configured to build the WASM version when using - the option WEBP_BUILD_WEBP_JS=ON. The compilation step will assemble - the files 'webp_wasm.js', 'webp_wasm.wasm' in the webp_js/ directory. - See webp_js/index_wasm.html for a simple demo page using the WASM version - of the library. - - You will need a fairly recent version of Emscripten (at least 2.0.18, - latest-upstream is recommended) and of your WASM-enabled browser to run this - version. - -Caveat: -======= - - - First decoding using the library is usually slower, due to just-in-time - compilation. - - - Some versions of llvm produce the following compile error when SSE2 is - enabled. - -"Unsupported: %516 = bitcast <8 x i16> %481 to i128 - LLVM ERROR: BitCast Instruction not yet supported for integer types larger than 64 bits" - - The corresponding Emscripten bug is at: - https://github.com/kripken/emscripten/issues/3788 - - Therefore, SSE2 optimization is currently disabled in CMakeLists.txt. - - - If WEBP_ENABLE_SIMD is set to 1 the JavaScript version (webp.js) will be - disabled as wasm2js does not support SIMD. diff --git a/doc/README b/doc/README deleted file mode 100644 index c49d7d18..00000000 --- a/doc/README +++ /dev/null @@ -1,29 +0,0 @@ - -Generate libwebp Container Spec Docs from Text Source -===================================================== - -HTML generation requires kramdown [1], easily installed as a -rubygem [2]. Rubygems installation should satisfy dependencies -automatically. - -[1]: https://kramdown.gettalong.org/ -[2]: https://rubygems.org/ - -HTML generation can then be done from the project root: - -$ kramdown doc/webp-container-spec.txt --template doc/template.html > \ - doc/output/webp-container-spec.html - -kramdown can optionally syntax highlight code blocks, using CodeRay [3], -a dependency of kramdown that rubygems will install automatically. The -following will apply inline CSS styling; an external stylesheet is not -needed. - -$ kramdown doc/webp-lossless-bitstream-spec.txt --template \ - doc/template.html --coderay-css style --coderay-line-numbers ' ' \ - --coderay-default-lang c > \ - doc/output/webp-lossless-bitstream-spec.html - -Optimally, use kramdown 0.13.7 or newer if syntax highlighting desired. - -[3]: https://github.com/rubychan/coderay diff --git a/doc/api.md b/doc/api.md new file mode 100644 index 00000000..d0adafbd --- /dev/null +++ b/doc/api.md @@ -0,0 +1,385 @@ +# WebP APIs + +## Encoding API + +The main encoding functions are available in the header src/webp/encode.h + +The ready-to-use ones are: + +```c +size_t WebPEncodeRGB(const uint8_t* rgb, int width, int height, int stride, + float quality_factor, uint8_t** output); +size_t WebPEncodeBGR(const uint8_t* bgr, int width, int height, int stride, + float quality_factor, uint8_t** output); +size_t WebPEncodeRGBA(const uint8_t* rgba, int width, int height, int stride, + float quality_factor, uint8_t** output); +size_t WebPEncodeBGRA(const uint8_t* bgra, int width, int height, int stride, + float quality_factor, uint8_t** output); +``` + +They will convert raw RGB samples to a WebP data. The only control supplied is +the quality factor. + +There are some variants for using the lossless format: + +```c +size_t WebPEncodeLosslessRGB(const uint8_t* rgb, int width, int height, + int stride, uint8_t** output); +size_t WebPEncodeLosslessBGR(const uint8_t* bgr, int width, int height, + int stride, uint8_t** output); +size_t WebPEncodeLosslessRGBA(const uint8_t* rgba, int width, int height, + int stride, uint8_t** output); +size_t WebPEncodeLosslessBGRA(const uint8_t* bgra, int width, int height, + int stride, uint8_t** output); +``` + +Of course in this case, no quality factor is needed since the compression occurs +without loss of the input values, at the expense of larger output sizes. + +### Advanced encoding API + +A more advanced API is based on the WebPConfig and WebPPicture structures. + +WebPConfig contains the encoding settings and is not tied to a particular +picture. WebPPicture contains input data, on which some WebPConfig will be used +for compression. The encoding flow looks like: + +```c +#include + +// Setup a config, starting form a preset and tuning some additional +// parameters +WebPConfig config; +if (!WebPConfigPreset(&config, WEBP_PRESET_PHOTO, quality_factor)) { + return 0; // version error +} +// ... additional tuning +config.sns_strength = 90; +config.filter_sharpness = 6; +config_error = WebPValidateConfig(&config); // not mandatory, but useful + +// Setup the input data +WebPPicture pic; +if (!WebPPictureInit(&pic)) { + return 0; // version error +} +pic.width = width; +pic.height = height; +// allocated picture of dimension width x height +if (!WebPPictureAlloc(&pic)) { + return 0; // memory error +} +// at this point, 'pic' has been initialized as a container, +// and can receive the Y/U/V samples. +// Alternatively, one could use ready-made import functions like +// WebPPictureImportRGB(), which will take care of memory allocation. +// In any case, past this point, one will have to call +// WebPPictureFree(&pic) to reclaim memory. + +// Set up a byte-output write method. WebPMemoryWriter, for instance. +WebPMemoryWriter wrt; +WebPMemoryWriterInit(&wrt); // initialize 'wrt' + +pic.writer = MyFileWriter; +pic.custom_ptr = my_opaque_structure_to_make_MyFileWriter_work; + +// Compress! +int ok = WebPEncode(&config, &pic); // ok = 0 => error occurred! +WebPPictureFree(&pic); // must be called independently of the 'ok' result. + +// output data should have been handled by the writer at that point. +// -> compressed data is the memory buffer described by wrt.mem / wrt.size + +// deallocate the memory used by compressed data +WebPMemoryWriterClear(&wrt); +``` + +## Decoding API + +This is mainly just one function to call: + +```c +#include "webp/decode.h" +uint8_t* WebPDecodeRGB(const uint8_t* data, size_t data_size, + int* width, int* height); +``` + +Please have a look at the file src/webp/decode.h for the details. There are +variants for decoding in BGR/RGBA/ARGB/BGRA order, along with decoding to raw +Y'CbCr samples. One can also decode the image directly into a pre-allocated +buffer. + +To detect a WebP file and gather the picture's dimensions, the function: + +```c +int WebPGetInfo(const uint8_t* data, size_t data_size, + int* width, int* height); +``` + +is supplied. No decoding is involved when using it. + +### Incremental decoding API + +In the case when data is being progressively transmitted, pictures can still be +incrementally decoded using a slightly more complicated API. Decoder state is +stored into an instance of the WebPIDecoder object. This object can be created +with the purpose of decoding either RGB or Y'CbCr samples. For instance: + +```c +WebPDecBuffer buffer; +WebPInitDecBuffer(&buffer); +buffer.colorspace = MODE_BGR; +... +WebPIDecoder* idec = WebPINewDecoder(&buffer); +``` + +As data is made progressively available, this incremental-decoder object can be +used to decode the picture further. There are two (mutually exclusive) ways to +pass freshly arrived data: + +either by appending the fresh bytes: + +```c +WebPIAppend(idec, fresh_data, size_of_fresh_data); +``` + +or by just mentioning the new size of the transmitted data: + +```c +WebPIUpdate(idec, buffer, size_of_transmitted_buffer); +``` + +Note that 'buffer' can be modified between each call to WebPIUpdate, in +particular when the buffer is resized to accommodate larger data. + +These functions will return the decoding status: either VP8_STATUS_SUSPENDED if +decoding is not finished yet or VP8_STATUS_OK when decoding is done. Any other +status is an error condition. + +The 'idec' object must always be released (even upon an error condition) by +calling: WebPDelete(idec). + +To retrieve partially decoded picture samples, one must use the corresponding +method: WebPIDecGetRGB or WebPIDecGetYUVA. It will return the last displayable +pixel row. + +Lastly, note that decoding can also be performed into a pre-allocated pixel +buffer. This buffer must be passed when creating a WebPIDecoder, calling +WebPINewRGB() or WebPINewYUVA(). + +Please have a look at the src/webp/decode.h header for further details. + +### Advanced Decoding API + +WebP decoding supports an advanced API which provides on-the-fly cropping and +rescaling, something of great usefulness on memory-constrained environments like +mobile phones. Basically, the memory usage will scale with the output's size, +not the input's, when one only needs a quick preview or a zoomed in portion of +an otherwise too-large picture. Some CPU can be saved too, incidentally. + +```c +// A) Init a configuration object +WebPDecoderConfig config; +CHECK(WebPInitDecoderConfig(&config)); + +// B) optional: retrieve the bitstream's features. +CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK); + +// C) Adjust 'config' options, if needed +config.options.no_fancy_upsampling = 1; +config.options.use_scaling = 1; +config.options.scaled_width = scaledWidth(); +config.options.scaled_height = scaledHeight(); +// etc. + +// D) Specify 'config' output options for specifying output colorspace. +// Optionally the external image decode buffer can also be specified. +config.output.colorspace = MODE_BGRA; +// Optionally, the config.output can be pointed to an external buffer as +// well for decoding the image. This externally supplied memory buffer +// should be big enough to store the decoded picture. +config.output.u.RGBA.rgba = (uint8_t*) memory_buffer; +config.output.u.RGBA.stride = scanline_stride; +config.output.u.RGBA.size = total_size_of_the_memory_buffer; +config.output.is_external_memory = 1; + +// E) Decode the WebP image. There are two variants w.r.t decoding image. +// The first one (E.1) decodes the full image and the second one (E.2) is +// used to incrementally decode the image using small input buffers. +// Any one of these steps can be used to decode the WebP image. + +// E.1) Decode full image. +CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK); + +// E.2) Decode image incrementally. +WebPIDecoder* const idec = WebPIDecode(NULL, NULL, &config); +CHECK(idec != NULL); +while (bytes_remaining > 0) { + VP8StatusCode status = WebPIAppend(idec, input, bytes_read); + if (status == VP8_STATUS_OK || status == VP8_STATUS_SUSPENDED) { + bytes_remaining -= bytes_read; + } else { + break; + } +} +WebPIDelete(idec); + +// F) Decoded image is now in config.output (and config.output.u.RGBA). +// It can be saved, displayed or otherwise processed. + +// G) Reclaim memory allocated in config's object. It's safe to call +// this function even if the memory is external and wasn't allocated +// by WebPDecode(). +WebPFreeDecBuffer(&config.output); +``` + +## Webp Mux + +WebPMux is a set of two libraries 'Mux' and 'Demux' for creation, extraction and +manipulation of an extended format WebP file, which can have features like color +profile, metadata and animation. Reference command-line tools `webpmux` and +`vwebp` as well as the WebP container specification +'doc/webp-container-spec.txt' are also provided in this package, see the +[tools documentation](tools.md). + +### Mux API + +The Mux API contains methods for adding data to and reading data from WebP +files. This API currently supports XMP/EXIF metadata, ICC profile and animation. +Other features may be added in subsequent releases. + +Example#1 (pseudo code): Creating a WebPMux object with image data, color +profile and XMP metadata. + +```c +int copy_data = 0; +WebPMux* mux = WebPMuxNew(); +// ... (Prepare image data). +WebPMuxSetImage(mux, &image, copy_data); +// ... (Prepare ICC profile data). +WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data); +// ... (Prepare XMP metadata). +WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data); +// Get data from mux in WebP RIFF format. +WebPMuxAssemble(mux, &output_data); +WebPMuxDelete(mux); +// ... (Consume output_data; e.g. write output_data.bytes to file). +WebPDataClear(&output_data); +``` + +Example#2 (pseudo code): Get image and color profile data from a WebP file. + +```c +int copy_data = 0; +// ... (Read data from file). +WebPMux* mux = WebPMuxCreate(&data, copy_data); +WebPMuxGetFrame(mux, 1, &image); +// ... (Consume image; e.g. call WebPDecode() to decode the data). +WebPMuxGetChunk(mux, "ICCP", &icc_profile); +// ... (Consume icc_profile). +WebPMuxDelete(mux); +free(data); +``` + +For a detailed Mux API reference, please refer to the header file +(src/webp/mux.h). + +### Demux API + +The Demux API enables extraction of images and extended format data from WebP +files. This API currently supports reading of XMP/EXIF metadata, ICC profile and +animated images. Other features may be added in subsequent releases. + +Code example: Demuxing WebP data to extract all the frames, ICC profile and +EXIF/XMP metadata. + +```c +WebPDemuxer* demux = WebPDemux(&webp_data); +uint32_t width = WebPDemuxGetI(demux, WEBP_FF_CANVAS_WIDTH); +uint32_t height = WebPDemuxGetI(demux, WEBP_FF_CANVAS_HEIGHT); +// ... (Get information about the features present in the WebP file). +uint32_t flags = WebPDemuxGetI(demux, WEBP_FF_FORMAT_FLAGS); + +// ... (Iterate over all frames). +WebPIterator iter; +if (WebPDemuxGetFrame(demux, 1, &iter)) { + do { + // ... (Consume 'iter'; e.g. Decode 'iter.fragment' with WebPDecode(), + // ... and get other frame properties like width, height, offsets etc. + // ... see 'struct WebPIterator' below for more info). + } while (WebPDemuxNextFrame(&iter)); + WebPDemuxReleaseIterator(&iter); +} + +// ... (Extract metadata). +WebPChunkIterator chunk_iter; +if (flags & ICCP_FLAG) WebPDemuxGetChunk(demux, "ICCP", 1, &chunk_iter); +// ... (Consume the ICC profile in 'chunk_iter.chunk'). +WebPDemuxReleaseChunkIterator(&chunk_iter); +if (flags & EXIF_FLAG) WebPDemuxGetChunk(demux, "EXIF", 1, &chunk_iter); +// ... (Consume the EXIF metadata in 'chunk_iter.chunk'). +WebPDemuxReleaseChunkIterator(&chunk_iter); +if (flags & XMP_FLAG) WebPDemuxGetChunk(demux, "XMP ", 1, &chunk_iter); +// ... (Consume the XMP metadata in 'chunk_iter.chunk'). +WebPDemuxReleaseChunkIterator(&chunk_iter); +WebPDemuxDelete(demux); +``` + +For a detailed Demux API reference, please refer to the header file +(src/webp/demux.h). + +## AnimEncoder API + +The AnimEncoder API can be used to create animated WebP images. + +Code example: + +```c +WebPAnimEncoderOptions enc_options; +WebPAnimEncoderOptionsInit(&enc_options); +// ... (Tune 'enc_options' as needed). +WebPAnimEncoder* enc = WebPAnimEncoderNew(width, height, &enc_options); +while() { + WebPConfig config; + WebPConfigInit(&config); + // ... (Tune 'config' as needed). + WebPAnimEncoderAdd(enc, frame, duration, &config); +} +WebPAnimEncoderAssemble(enc, webp_data); +WebPAnimEncoderDelete(enc); +// ... (Write the 'webp_data' to a file, or re-mux it further). +``` + +For a detailed AnimEncoder API reference, please refer to the header file +(src/webp/mux.h). + +## AnimDecoder API + +This AnimDecoder API allows decoding (possibly) animated WebP images. + +Code Example: + +```c +WebPAnimDecoderOptions dec_options; +WebPAnimDecoderOptionsInit(&dec_options); +// Tune 'dec_options' as needed. +WebPAnimDecoder* dec = WebPAnimDecoderNew(webp_data, &dec_options); +WebPAnimInfo anim_info; +WebPAnimDecoderGetInfo(dec, &anim_info); +for (uint32_t i = 0; i < anim_info.loop_count; ++i) { + while (WebPAnimDecoderHasMoreFrames(dec)) { + uint8_t* buf; + int timestamp; + WebPAnimDecoderGetNext(dec, &buf, ×tamp); + // ... (Render 'buf' based on 'timestamp'). + // ... (Do NOT free 'buf', as it is owned by 'dec'). + } + WebPAnimDecoderReset(dec); +} +const WebPDemuxer* demuxer = WebPAnimDecoderGetDemuxer(dec); +// ... (Do something using 'demuxer'; e.g. get EXIF/XMP/ICC data). +WebPAnimDecoderDelete(dec); +``` + +For a detailed AnimDecoder API reference, please refer to the header file +(src/webp/demux.h). diff --git a/doc/building.md b/doc/building.md new file mode 100644 index 00000000..5efeab9a --- /dev/null +++ b/doc/building.md @@ -0,0 +1,213 @@ +# Building + +## Windows build + +By running: + +```batch +nmake /f Makefile.vc CFG=release-static RTLIBCFG=static OBJDIR=output +``` + +the directory `output\release-static\(x64|x86)\bin` will contain the tools +cwebp.exe and dwebp.exe. The directory `output\release-static\(x64|x86)\lib` +will contain the libwebp static library. The target architecture (x86/x64) is +detected by Makefile.vc from the Visual Studio compiler (cl.exe) available in +the system path. + +## Unix build using makefile.unix + +On platforms with GNU tools installed (gcc and make), running + +```shell +make -f makefile.unix +``` + +will build the binaries examples/cwebp and examples/dwebp, along with the static +library src/libwebp.a. No system-wide installation is supplied, as this is a +simple alternative to the full installation system based on the autoconf tools +(see below). Please refer to makefile.unix for additional details and +customizations. + +## Using autoconf tools + +Prerequisites: a compiler (e.g., gcc), make, autoconf, automake, libtool. + +On a Debian-like system the following should install everything you need for a +minimal build: + +```shell +$ sudo apt-get install gcc make autoconf automake libtool +``` + +When building from git sources, you will need to run autogen.sh to generate the +configure script. + +```shell +./configure +make +make install +``` + +should be all you need to have the following files + +``` +/usr/local/include/webp/decode.h +/usr/local/include/webp/encode.h +/usr/local/include/webp/types.h +/usr/local/lib/libwebp.* +/usr/local/bin/cwebp +/usr/local/bin/dwebp +``` + +installed. + +Note: A decode-only library, libwebpdecoder, is available using the +`--enable-libwebpdecoder` flag. The encode library is built separately and can +be installed independently using a minor modification in the corresponding +Makefile.am configure files (see comments there). See `./configure --help` for +more options. + +## Building for MIPS Linux + +MIPS Linux toolchain stable available releases can be found at: +https://community.imgtec.com/developers/mips/tools/codescape-mips-sdk/available-releases/ + +```shell +# Add toolchain to PATH +export PATH=$PATH:/path/to/toolchain/bin + +# 32-bit build for mips32r5 (p5600) +HOST=mips-mti-linux-gnu +MIPS_CFLAGS="-O3 -mips32r5 -mabi=32 -mtune=p5600 -mmsa -mfp64 \ + -msched-weight -mload-store-pairs -fPIE" +MIPS_LDFLAGS="-mips32r5 -mabi=32 -mmsa -mfp64 -pie" + +# 64-bit build for mips64r6 (i6400) +HOST=mips-img-linux-gnu +MIPS_CFLAGS="-O3 -mips64r6 -mabi=64 -mtune=i6400 -mmsa -mfp64 \ + -msched-weight -mload-store-pairs -fPIE" +MIPS_LDFLAGS="-mips64r6 -mabi=64 -mmsa -mfp64 -pie" + +./configure --host=${HOST} --build=`config.guess` \ + CC="${HOST}-gcc -EL" \ + CFLAGS="$MIPS_CFLAGS" \ + LDFLAGS="$MIPS_LDFLAGS" +make +make install +``` + +## CMake + +With CMake, you can compile libwebp, cwebp, dwebp, gif2webp, img2webp, webpinfo +and the JS bindings. + +Prerequisites: a compiler (e.g., gcc with autotools) and CMake. + +On a Debian-like system the following should install everything you need for a +minimal build: + +```shell +$ sudo apt-get install build-essential cmake +``` + +When building from git sources, you will need to run cmake to generate the +makefiles. + +```shell +mkdir build && cd build && cmake ../ +make +make install +``` + +If you also want any of the executables, you will need to enable them through +CMake, e.g.: + +```shell +cmake -DWEBP_BUILD_CWEBP=ON -DWEBP_BUILD_DWEBP=ON ../ +``` + +or through your favorite interface (like ccmake or cmake-qt-gui). + +Use option `-DWEBP_UNICODE=ON` for Unicode support on Windows (with chcp 65001). + +Finally, once installed, you can also use WebP in your CMake project by doing: + +```cmake +find_package(WebP) +``` + +which will define the CMake variables WebP_INCLUDE_DIRS and WebP_LIBRARIES. + +## Gradle + +The support for Gradle is minimal: it only helps you compile libwebp, cwebp and +dwebp and webpmux_example. + +Prerequisites: a compiler (e.g., gcc with autotools) and gradle. + +On a Debian-like system the following should install everything you need for a +minimal build: + +```shell +$ sudo apt-get install build-essential gradle +``` + +When building from git sources, you will need to run the Gradle wrapper with the +appropriate target, e.g. : + +```shell +./gradlew buildAllExecutables +``` + +## SWIG bindings + +To generate language bindings from swig/libwebp.swig at least swig-1.3 +(http://www.swig.org) is required. + +Currently the following functions are mapped: + +Decode: + +``` +WebPGetDecoderVersion +WebPGetInfo +WebPDecodeRGBA +WebPDecodeARGB +WebPDecodeBGRA +WebPDecodeBGR +WebPDecodeRGB +``` + +Encode: + +``` +WebPGetEncoderVersion +WebPEncodeRGBA +WebPEncodeBGRA +WebPEncodeRGB +WebPEncodeBGR +WebPEncodeLosslessRGBA +WebPEncodeLosslessBGRA +WebPEncodeLosslessRGB +WebPEncodeLosslessBGR +``` + +See also the [swig documentation](../swig/README.md) for more detailed build +instructions and usage examples. + +### Java bindings + +To build the swig-generated JNI wrapper code at least JDK-1.5 (or equivalent) is +necessary for enum support. The output is intended to be a shared object / DLL +that can be loaded via `System.loadLibrary("webp_jni")`. + +### Python bindings + +To build the swig-generated Python extension code at least Python 2.6 is +required. Python < 2.6 may build with some minor changes to libwebp.swig or the +generated code, but is untested. + +## Javascript decoder + +Libwebp can be compiled into a JavaScript decoder using Emscripten and CMake. +See the [corresponding documentation](../README.md) diff --git a/doc/specs_generation.md b/doc/specs_generation.md new file mode 100644 index 00000000..0380d664 --- /dev/null +++ b/doc/specs_generation.md @@ -0,0 +1,26 @@ +# Generate libwebp Container Spec Docs from Text Source + +HTML generation requires [kramdown](https://kramdown.gettalong.org/), easily +installed as a [rubygem](https://rubygems.org/). Rubygems installation should +satisfy dependencies automatically. + +HTML generation can then be done from the project root: + +```shell +$ kramdown doc/webp-container-spec.txt --template doc/template.html > \ + doc/output/webp-container-spec.html +``` + +kramdown can optionally syntax highlight code blocks, using +[CodeRay](https://github.com/rubychan/coderay), a dependency of kramdown that +rubygems will install automatically. The following will apply inline CSS +styling; an external stylesheet is not needed. + +```shell +$ kramdown doc/webp-lossless-bitstream-spec.txt --template \ + doc/template.html --coderay-css style --coderay-line-numbers ' ' \ + --coderay-default-lang c > \ + doc/output/webp-lossless-bitstream-spec.html +``` + +Optimally, use kramdown 0.13.7 or newer if syntax highlighting desired. diff --git a/doc/tools.md b/doc/tools.md new file mode 100644 index 00000000..70958c45 --- /dev/null +++ b/doc/tools.md @@ -0,0 +1,512 @@ +# WebP tools + +## Encoding tool + +The examples/ directory contains tools for encoding (cwebp) and decoding (dwebp) +images. + +The easiest use should look like: + +```shell +cwebp input.png -q 80 -o output.webp +``` + +which will convert the input file to a WebP file using a quality factor of 80 on +a 0->100 scale (0 being the lowest quality, 100 being the best. Default value is +75). + +You might want to try the `-lossless` flag too, which will compress the source +(in RGBA format) without any loss. The `-q` quality parameter will in this case +control the amount of processing time spent trying to make the output file as +small as possible. + +A longer list of options is available using the `-longhelp` command line flag: + +```shell +> cwebp -longhelp +Usage: + cwebp [-preset <...>] [options] in_file [-o out_file] +``` + +If input size (-s) for an image is not specified, it is assumed to be a PNG, +JPEG, TIFF or WebP file. Note: Animated PNG and WebP files are not supported. + +Options: + +``` +-h / -help ............. short help +-H / -longhelp ......... long help +-q ............. quality factor (0:small..100:big), default=75 +-alpha_q ......... transparency-compression quality (0..100), + default=100 +-preset ....... preset setting, one of: + default, photo, picture, + drawing, icon, text + -preset must come first, as it overwrites other parameters +-z ............... activates lossless preset with given + level in [0:fast, ..., 9:slowest] + +-m ............... compression method (0=fast, 6=slowest), default=4 +-segments ........ number of segments to use (1..4), default=4 +-size ............ target size (in bytes) +-psnr .......... target PSNR (in dB. typically: 42) + +-s ......... input size (width x height) for YUV +-sns ............. spatial noise shaping (0:off, 100:max), default=50 +-f ............... filter strength (0=off..100), default=60 +-sharpness ....... filter sharpness (0:most .. 7:least sharp), default=0 +-strong ................ use strong filter instead of simple (default) +-nostrong .............. use simple filter instead of strong +-sharp_yuv ............. use sharper (and slower) RGB->YUV conversion +-partition_limit . limit quality to fit the 512k limit on + the first partition (0=no degradation ... 100=full) +-pass ............ analysis pass number (1..10) +-qrange .... specifies the permissible quality range + (default: 0 100) +-crop .. crop picture with the given rectangle +-resize ........ resize picture (after any cropping) +-mt .................... use multi-threading if available +-low_memory ............ reduce memory usage (slower encoding) +-map ............. print map of extra info +-print_psnr ............ prints averaged PSNR distortion +-print_ssim ............ prints averaged SSIM distortion +-print_lsim ............ prints local-similarity distortion +-d .......... dump the compressed output (PGM file) +-alpha_method .... transparency-compression method (0..1), default=1 +-alpha_filter . predictive filtering for alpha plane, + one of: none, fast (default) or best +-exact ................. preserve RGB values in transparent area, default=off +-blend_alpha ..... blend colors against background color + expressed as RGB values written in + hexadecimal, e.g. 0xc0e0d0 for red=0xc0 + green=0xe0 and blue=0xd0 +-noalpha ............... discard any transparency information +-lossless .............. encode image losslessly, default=off +-near_lossless ... use near-lossless image + preprocessing (0..100=off), default=100 +-hint ......... specify image characteristics hint, + one of: photo, picture or graph + +-metadata ..... comma separated list of metadata to + copy from the input to the output if present. + Valid values: all, none (default), exif, icc, xmp + +-short ................. condense printed message +-quiet ................. don't print anything +-version ............... print version number and exit +-noasm ................. disable all assembly optimizations +-v ..................... verbose, e.g. print encoding/decoding times +-progress .............. report encoding progress +``` + +Experimental Options: + +``` +-jpeg_like ............. roughly match expected JPEG size +-af .................... auto-adjust filter strength +-pre ............. pre-processing filter +``` + +The main options you might want to try in order to further tune the visual +quality are: + +-preset -sns -f -m + +Namely: + +* `preset` will set up a default encoding configuration targeting a particular + type of input. It should appear first in the list of options, so that + subsequent options can take effect on top of this preset. Default value is + 'default'. +* `sns` will progressively turn on (when going from 0 to 100) some additional + visual optimizations (like: segmentation map re-enforcement). This option + will balance the bit allocation differently. It tries to take bits from the + "easy" parts of the picture and use them in the "difficult" ones instead. + Usually, raising the sns value (at fixed -q value) leads to larger files, + but with better quality. Typical value is around '75'. +* `f` option directly links to the filtering strength used by the codec's + in-loop processing. The higher the value, the smoother the highly-compressed + area will look. This is particularly useful when aiming at very small files. + Typical values are around 20-30. Note that using the option + -strong/-nostrong will change the type of filtering. Use "-f 0" to turn + filtering off. +* `m` controls the trade-off between encoding speed and quality. Default is 4. + You can try -m 5 or -m 6 to explore more (time-consuming) encoding + possibilities. A lower value will result in faster encoding at the expense + of quality. + +## Decoding tool + +There is a decoding sample in examples/dwebp.c which will take a .webp file and +decode it to a PNG image file (amongst other formats). This is simply to +demonstrate the use of the API. You can verify the file test.webp decodes to +exactly the same as test_ref.ppm by using: + +```shell +cd examples +./dwebp test.webp -ppm -o test.ppm +diff test.ppm test_ref.ppm +``` + +The full list of options is available using -h: + +```shell +> dwebp -h +Usage: dwebp in_file [options] [-o out_file] +``` + +Decodes the WebP image file to PNG format [Default]. Note: Animated WebP files +are not supported. + +Use following options to convert into alternate image formats: + +``` +-pam ......... save the raw RGBA samples as a color PAM +-ppm ......... save the raw RGB samples as a color PPM +-bmp ......... save as uncompressed BMP format +-tiff ........ save as uncompressed TIFF format +-pgm ......... save the raw YUV samples as a grayscale PGM + file with IMC4 layout +-yuv ......... save the raw YUV samples in flat layout +``` + +Other options are: + +``` +-version ..... print version number and exit +-nofancy ..... don't use the fancy YUV420 upscaler +-nofilter .... disable in-loop filtering +-nodither .... disable dithering +-dither .. dithering strength (in 0..100) +-alpha_dither use alpha-plane dithering if needed +-mt .......... use multi-threading +-crop ... crop output with the given rectangle +-resize ......... scale the output (*after* any cropping) +-flip ........ flip the output vertically +-alpha ....... only save the alpha plane +-incremental . use incremental decoding (useful for tests) +-h ........... this help message +-v ........... verbose (e.g. print encoding/decoding times) +-quiet ....... quiet mode, don't print anything +-noasm ....... disable all assembly optimizations +``` + +## WebP file analysis tool + +`webpinfo` can be used to print out the chunk level structure and bitstream +header information of WebP files. It can also check if the files are of valid +WebP format. + +Usage: + +```shell +webpinfo [options] in_files +``` + +Note: there could be multiple input files; options must come before input files. + +Options: + +``` +-version ........... Print version number and exit. +-quiet ............. Do not show chunk parsing information. +-diag .............. Show parsing error diagnosis. +-summary ........... Show chunk stats summary. +-bitstream_info .... Parse bitstream header. +``` + +## Visualization tool + +There's a little self-serve visualization tool called 'vwebp' under the +examples/ directory. It uses OpenGL to open a simple drawing window and show a +decoded WebP file. It's not yet integrated in the automake build system, but you +can try to manually compile it using the recommendations below. + +Usage: + +```shell +vwebp in_file [options] +``` + +Decodes the WebP image file and visualize it using OpenGL + +Options are: + +``` +-version ..... print version number and exit +-noicc ....... don't use the icc profile if present +-nofancy ..... don't use the fancy YUV420 upscaler +-nofilter .... disable in-loop filtering +-dither dithering strength (0..100), default=50 +-noalphadither disable alpha plane dithering +-usebgcolor .. display background color +-mt .......... use multi-threading +-info ........ print info +-h ........... this help message +``` + +Keyboard shortcuts: + +``` +'c' ................ toggle use of color profile +'b' ................ toggle background color display +'i' ................ overlay file information +'d' ................ disable blending & disposal (debug) +'q' / 'Q' / ESC .... quit +``` + +### Building + +Prerequisites: + +1. OpenGL & OpenGL Utility Toolkit (GLUT) + + Linux: `sudo apt-get install freeglut3-dev mesa-common-dev` + + Mac + Xcode: These libraries should be available in the OpenGL / GLUT + frameworks. + + Windows: http://freeglut.sourceforge.net/index.php#download + +2. (Optional) qcms (Quick Color Management System) + + 1. Download qcms from Mozilla / Chromium: + https://hg.mozilla.org/mozilla-central/file/0e7639e3bdfb/gfx/qcms + https://source.chromium.org/chromium/chromium/src/+/main:third_party/qcms/;drc=d4a2f8e1ed461d8fc05ed88d1ae2dc94c9773825 + 2. Build and archive the source files as libqcms.a / qcms.lib + 3. Update makefile.unix / Makefile.vc + 1. Define WEBP_HAVE_QCMS + 2. Update include / library paths to reference the qcms directory. + +Build using makefile.unix / Makefile.vc: + +```shell +$ make -f makefile.unix examples/vwebp +> nmake /f Makefile.vc CFG=release-static \ + ../obj/x64/release-static/bin/vwebp.exe +``` + +## Animation creation tool + +The utility `img2webp` can turn a sequence of input images (PNG, JPEG, ...) into +an animated WebP file. It offers fine control over duration, encoding modes, +etc. + +Usage: + +```shell +img2webp [file_options] [[frame_options] frame_file]... +``` + +File-level options (only used at the start of compression): + +``` +-min_size ............ minimize size +-loop .......... loop count (default: 0, = infinite loop) +-kmax .......... maximum number of frame between key-frames + (0=only keyframes) +-kmin .......... minimum number of frame between key-frames + (0=disable key-frames altogether) +-mixed ............... use mixed lossy/lossless automatic mode +-v ................... verbose mode +-h ................... this help +-version ............. print version number and exit +``` + +Per-frame options (only used for subsequent images input): + +``` +-d ............. frame duration in ms (default: 100) +-lossless ........... use lossless mode (default) +-lossy ... ........... use lossy mode +-q ........... quality +-m ............. method to use +``` + +example: `img2webp -loop 2 in0.png -lossy in1.jpg -d 80 in2.tiff -o out.webp` + +Note: if a single file name is passed as the argument, the arguments will be +tokenized from this file. The file name must not start with the character '-'. + +## Animated GIF conversion + +Animated GIF files can be converted to WebP files with animation using the +gif2webp utility available under examples/. The files can then be viewed using +vwebp. + +Usage: + +```shell +gif2webp [options] gif_file -o webp_file +``` + +Options: + +``` +-h / -help ............. this help +-lossy ................. encode image using lossy compression +-mixed ................. for each frame in the image, pick lossy + or lossless compression heuristically +-q ............. quality factor (0:small..100:big) +-m ............... compression method (0=fast, 6=slowest) +-min_size .............. minimize output size (default:off) + lossless compression by default; can be + combined with -q, -m, -lossy or -mixed + options +-kmin ............ min distance between key frames +-kmax ............ max distance between key frames +-f ............... filter strength (0=off..100) +-metadata ..... comma separated list of metadata to + copy from the input to the output if present + Valid values: all, none, icc, xmp (default) +-loop_compatibility .... use compatibility mode for Chrome + version prior to M62 (inclusive) +-mt .................... use multi-threading if available + +-version ............... print version number and exit +-v ..................... verbose +-quiet ................. don't print anything +``` + +### Building + +With the libgif development files installed, gif2webp can be built using +makefile.unix: + +```shell +$ make -f makefile.unix examples/gif2webp +``` + +or using autoconf: + +```shell +$ ./configure --enable-everything +$ make +``` + +## Comparison of animated images + +Test utility anim_diff under examples/ can be used to compare two animated +images (each can be GIF or WebP). + +Usage: + +```shell +anim_diff [options] +``` + +Options: + +``` +-dump_frames dump decoded frames in PAM format +-min_psnr ... minimum per-frame PSNR +-raw_comparison ..... if this flag is not used, RGB is + premultiplied before comparison +-max_diff ..... maximum allowed difference per channel + between corresponding pixels in subsequent + frames +-h .................. this help +-version ............ print version number and exit +``` + +### Building + +With the libgif development files installed, anim_diff can be built using +makefile.unix: + +```shell +$ make -f makefile.unix examples/anim_diff +``` + +or using autoconf: + +```shell +$ ./configure --enable-everything +$ make +``` + +## WebP Mux tool + +The examples/ directory contains a tool (webpmux) for manipulating WebP files. +The webpmux tool can be used to create an extended format WebP file and also to +extract or strip relevant data from such a file. + +A list of options is available using the -help command line flag: + +```shell +> webpmux -help +Usage: webpmux -get GET_OPTIONS INPUT -o OUTPUT + webpmux -set SET_OPTIONS INPUT -o OUTPUT + webpmux -duration DURATION_OPTIONS [-duration ...] + INPUT -o OUTPUT + webpmux -strip STRIP_OPTIONS INPUT -o OUTPUT + webpmux -frame FRAME_OPTIONS [-frame...] [-loop LOOP_COUNT] + [-bgcolor BACKGROUND_COLOR] -o OUTPUT + webpmux -info INPUT + webpmux [-h|-help] + webpmux -version + webpmux argument_file_name + +GET_OPTIONS: + Extract relevant data: + icc get ICC profile + exif get EXIF metadata + xmp get XMP metadata + frame n get nth frame + +SET_OPTIONS: + Set color profile/metadata/parameters: + loop LOOP_COUNT set the loop count + bgcolor BACKGROUND_COLOR set the animation background color + icc file.icc set ICC profile + exif file.exif set EXIF metadata + xmp file.xmp set XMP metadata + where: 'file.icc' contains the ICC profile to be set, + 'file.exif' contains the EXIF metadata to be set + 'file.xmp' contains the XMP metadata to be set + +DURATION_OPTIONS: + Set duration of selected frames: + duration set duration for each frames + duration,frame set duration of a particular frame + duration,start,end set duration of frames in the + interval [start,end]) + where: 'duration' is the duration in milliseconds + 'start' is the start frame index + 'end' is the inclusive end frame index + The special 'end' value '0' means: last frame. + +STRIP_OPTIONS: + Strip color profile/metadata: + icc strip ICC profile + exif strip EXIF metadata + xmp strip XMP metadata + +FRAME_OPTIONS(i): + Create animation: + file_i +di+[xi+yi[+mi[bi]]] + where: 'file_i' is the i'th animation frame (WebP format), + 'di' is the pause duration before next frame, + 'xi','yi' specify the image offset for this frame, + 'mi' is the dispose method for this frame (0 or 1), + 'bi' is the blending method for this frame (+b or -b) + +LOOP_COUNT: + Number of times to repeat the animation. + Valid range is 0 to 65535 [Default: 0 (infinite)]. + +BACKGROUND_COLOR: + Background color of the canvas. + A,R,G,B + where: 'A', 'R', 'G' and 'B' are integers in the range 0 to 255 specifying + the Alpha, Red, Green and Blue component values respectively + [Default: 255,255,255,255] + +INPUT & OUTPUT are in WebP format. + +Note: The nature of EXIF, XMP and ICC data is not checked and is assumed to be +valid. + +Note: if a single file name is passed as the argument, the arguments will be +tokenized from this file. The file name must not start with the character '-'. +``` diff --git a/doc/webp-container-spec.txt b/doc/webp-container-spec.txt index ffa8940f..e421dc6c 100644 --- a/doc/webp-container-spec.txt +++ b/doc/webp-container-spec.txt @@ -4,8 +4,8 @@ Although you may be viewing an alternate representation, this document is sourced in Markdown, a light-duty markup scheme, and is optimized for the [kramdown](https://kramdown.gettalong.org/) transformer. -See the accompanying README. External link targets are referenced at the -end of this file. +See the accompanying specs_generation.md. External link targets are referenced +at the end of this file. --> diff --git a/doc/webp-lossless-bitstream-spec.txt b/doc/webp-lossless-bitstream-spec.txt index 07da15b4..96e8867c 100644 --- a/doc/webp-lossless-bitstream-spec.txt +++ b/doc/webp-lossless-bitstream-spec.txt @@ -4,8 +4,8 @@ Although you may be viewing an alternate representation, this document is sourced in Markdown, a light-duty markup scheme, and is optimized for the [kramdown](https://kramdown.gettalong.org/) transformer. -See the accompanying README. External link targets are referenced at the -end of this file. +See the accompanying specs_generation.md. External link targets are referenced +at the end of this file. --> diff --git a/swig/README b/swig/README.md similarity index 78% rename from swig/README rename to swig/README.md index 725c0716..7fa1c388 100644 --- a/swig/README +++ b/swig/README.md @@ -1,15 +1,20 @@ -Building: -========= +# SWIG bindings -JNI SWIG bindings: ------------------- +## Building + +### JNI SWIG bindings + +```shell $ gcc -shared -fPIC -fno-strict-aliasing -O2 \ -I/path/to/your/jdk/includes \ libwebp_java_wrap.c \ -lwebp \ -o libwebp_jni.so +``` --------------------------------------- BEGIN PSEUDO EXAMPLE +Example usage: + +```java import com.google.webp.libwebp; import java.lang.reflect.Method; @@ -33,17 +38,23 @@ public class libwebp_jni_example { } } } --------------------------------------- END PSEUDO EXAMPLE +``` +```shell $ javac -cp libwebp.jar libwebp_jni_example.java $ java -Djava.library.path=. -cp libwebp.jar:. libwebp_jni_example +``` -Python SWIG bindings: ---------------------- +### Python SWIG bindings: + +```shell $ python setup.py build_ext $ python setup.py install --prefix=pylocal +``` --------------------------------------- BEGIN PSEUDO EXAMPLE +Example usage: + +```python import glob import sys sys.path.append(glob.glob('pylocal/lib/python*/site-packages')[0]) @@ -53,4 +64,4 @@ print "libwebp decoder version: %x" % libwebp.WebPGetDecoderVersion() print "libwebp attributes:" for attr in dir(libwebp): print attr --------------------------------------- END PSEUDO EXAMPLE +``` diff --git a/tests/README b/tests/README deleted file mode 100644 index 2f806818..00000000 --- a/tests/README +++ /dev/null @@ -1,19 +0,0 @@ -Description: -============ - -This is a collection of tests for the libwebp libraries, currently covering -fuzzing through the APIs. Additional test vector coverage can be found at: -https://chromium.googlesource.com/webm/libwebp-test-data - -Building: -========= - -Fuzzers: --------- - -Follow the build instructions in ../README for libwebp, optionally adding build -flags for various sanitizers (e.g., -fsanitize=address). - -fuzzer/makefile.unix can then be used to compile the fuzzer targets: - -$ make -C fuzzer -f makefile.unix diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 00000000..91daba26 --- /dev/null +++ b/tests/README.md @@ -0,0 +1,18 @@ +# Tests + +This is a collection of tests for the libwebp libraries, currently covering +fuzzing through the APIs. Additional test vector coverage can be found at: +https://chromium.googlesource.com/webm/libwebp-test-data + +## Building + +### Fuzzers + +Follow the [build instructions](../doc/building.md) for libwebp, optionally +adding build flags for various sanitizers (e.g., -fsanitize=address). + +`fuzzer/makefile.unix` can then be used to compile the fuzzer targets: + +```shell +$ make -C fuzzer -f makefile.unix +``` diff --git a/webp_js/README.md b/webp_js/README.md new file mode 100644 index 00000000..174ca9fe --- /dev/null +++ b/webp_js/README.md @@ -0,0 +1,78 @@ +# Webp JavaScript decoder + +``` + __ __ ____ ____ ____ __ ____ +/ \\/ \ _ \ _ \ _ \ (__)/ __\ +\ / __/ _ \ __/ _) \_ \ + \__\__/_____/____/_/ /____/____/ +``` + +This file describes the compilation of libwebp into a JavaScript decoder using +Emscripten and CMake. + +- install the Emscripten SDK following the procedure described at: + https://emscripten.org/docs/getting_started/downloads.html#installation-instructions-using-the-emsdk-recommended + After installation, you should have some global variable positioned to the + location of the SDK. In particular, $EMSDK should point to the top-level + directory containing Emscripten tools. + +- configure the project 'WEBP_JS' with CMake using: + + ```shell + cd webp_js && \ + emcmake cmake -DWEBP_BUILD_WEBP_JS=ON \ + ../ + ``` + +- compile webp.js using 'emmake make'. + +- that's it! Upon completion, you should have the webp.js and webp.wasm files + generated. + +The callable JavaScript function is WebPToSDL(), which decodes a raw WebP +bitstream into a canvas. See webp_js/index.html for a simple usage sample (see +below for instructions). + +## Demo HTML page + +The HTML page webp_js/index.html requires an HTTP server to serve the WebP image +example. It's easy to just use Python for that. + +```shell +cd webp_js && python -m SimpleHTTPServer 8080 +``` + +and then navigate to http://localhost:8080 in your favorite browser. + +## Web-Assembly (WASM) version: + +CMakeLists.txt is configured to build the WASM version when using the option +WEBP_BUILD_WEBP_JS=ON. The compilation step will assemble the files +'webp_wasm.js', 'webp_wasm.wasm' in the webp_js/ directory. See +webp_js/index_wasm.html for a simple demo page using the WASM version of the +library. + +You will need a fairly recent version of Emscripten (at least 2.0.18, +latest-upstream is recommended) and of your WASM-enabled browser to run this +version. + +## Caveats + +- First decoding using the library is usually slower, due to just-in-time + compilation. + +- Some versions of llvm produce the following compile error when SSE2 is + enabled. + + ``` + "Unsupported: %516 = bitcast <8 x i16> %481 to i128 + LLVM ERROR: BitCast Instruction not yet supported for integer types larger than 64 bits" + ``` + + The corresponding Emscripten bug is at: + https://github.com/kripken/emscripten/issues/3788 + + Therefore, SSE2 optimization is currently disabled in CMakeLists.txt. + +- If WEBP_ENABLE_SIMD is set to 1 the JavaScript version (webp.js) will be + disabled as wasm2js does not support SIMD.