README 28 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750
  1. __ __ ____ ____ ____
  2. / \\/ \/ _ \/ _ )/ _ \
  3. \ / __/ _ \ __/
  4. \__\__/\____/\_____/__/ ____ ___
  5. / _/ / \ \ / _ \/ _/
  6. / \_/ / / \ \ __/ \__
  7. \____/____/\_____/_____/____/v0.6.0
  8. Description:
  9. ============
  10. WebP codec: library to encode and decode images in WebP format. This package
  11. contains the library that can be used in other programs to add WebP support,
  12. as well as the command line tools 'cwebp' and 'dwebp'.
  13. See http://developers.google.com/speed/webp
  14. The latest source tree is available at
  15. https://chromium.googlesource.com/webm/libwebp
  16. It is released under the same license as the WebM project.
  17. See http://www.webmproject.org/license/software/ or the
  18. "COPYING" file for details. An additional intellectual
  19. property rights grant can be found in the file PATENTS.
  20. Building:
  21. =========
  22. Windows build:
  23. --------------
  24. By running:
  25. nmake /f Makefile.vc CFG=release-static RTLIBCFG=static OBJDIR=output
  26. the directory output\release-static\(x64|x86)\bin will contain the tools
  27. cwebp.exe and dwebp.exe. The directory output\release-static\(x64|x86)\lib will
  28. contain the libwebp static library.
  29. The target architecture (x86/x64) is detected by Makefile.vc from the Visual
  30. Studio compiler (cl.exe) available in the system path.
  31. Unix build using makefile.unix:
  32. -------------------------------
  33. On platforms with GNU tools installed (gcc and make), running
  34. make -f makefile.unix
  35. will build the binaries examples/cwebp and examples/dwebp, along
  36. with the static library src/libwebp.a. No system-wide installation
  37. is supplied, as this is a simple alternative to the full installation
  38. system based on the autoconf tools (see below).
  39. Please refer to makefile.unix for additional details and customizations.
  40. Using autoconf tools:
  41. ---------------------
  42. Prerequisites:
  43. A compiler (e.g., gcc), make, autoconf, automake, libtool.
  44. On a Debian-like system the following should install everything you need for a
  45. minimal build:
  46. $ sudo apt-get install gcc make autoconf automake libtool
  47. When building from git sources, you will need to run autogen.sh to generate the
  48. configure script.
  49. ./configure
  50. make
  51. make install
  52. should be all you need to have the following files
  53. /usr/local/include/webp/decode.h
  54. /usr/local/include/webp/encode.h
  55. /usr/local/include/webp/types.h
  56. /usr/local/lib/libwebp.*
  57. /usr/local/bin/cwebp
  58. /usr/local/bin/dwebp
  59. installed.
  60. Note: A decode-only library, libwebpdecoder, is available using the
  61. '--enable-libwebpdecoder' flag. The encode library is built separately and can
  62. be installed independently using a minor modification in the corresponding
  63. Makefile.am configure files (see comments there). See './configure --help' for
  64. more options.
  65. Building for MIPS Linux:
  66. ------------------------
  67. MIPS Linux toolchain stable available releases can be found at:
  68. https://community.imgtec.com/developers/mips/tools/codescape-mips-sdk/available-releases/
  69. # Add toolchain to PATH
  70. export PATH=$PATH:/path/to/toolchain/bin
  71. # 32-bit build for mips32r5 (p5600)
  72. HOST=mips-mti-linux-gnu
  73. MIPS_CFLAGS="-O3 -mips32r5 -mabi=32 -mtune=p5600 -mmsa -mfp64 \
  74. -msched-weight -mload-store-pairs -fPIE"
  75. MIPS_LDFLAGS="-mips32r5 -mabi=32 -mmsa -mfp64 -pie"
  76. # 64-bit build for mips64r6 (i6400)
  77. HOST=mips-img-linux-gnu
  78. MIPS_CFLAGS="-O3 -mips64r6 -mabi=64 -mtune=i6400 -mmsa -mfp64 \
  79. -msched-weight -mload-store-pairs -fPIE"
  80. MIPS_LDFLAGS="-mips64r6 -mabi=64 -mmsa -mfp64 -pie"
  81. ./configure --host=${HOST} --build=`config.guess` \
  82. CC="${HOST}-gcc -EL" \
  83. CFLAGS="$MIPS_CFLAGS" \
  84. LDFLAGS="$MIPS_LDFLAGS"
  85. make
  86. make install
  87. CMake:
  88. ------
  89. The support for CMake is minimal: it only helps you compile libwebp, cwebp and
  90. dwebp.
  91. Prerequisites:
  92. A compiler (e.g., gcc with autotools) and CMake.
  93. On a Debian-like system the following should install everything you need for a
  94. minimal build:
  95. $ sudo apt-get install build-essential cmake
  96. When building from git sources, you will need to run cmake to generate the
  97. configure script.
  98. mkdir build && cd build && cmake ../
  99. make
  100. make install
  101. If you also want cwebp or dwebp, you will need to enable them through CMake:
  102. cmake -DWEBP_BUILD_CWEBP=ON -DWEBP_BUILD_DWEBP=ON ../
  103. or through your favorite interface (like ccmake or cmake-qt-gui).
  104. Gradle:
  105. -------
  106. The support for Gradle is minimal: it only helps you compile libwebp, cwebp and
  107. dwebp and webpmux_example.
  108. Prerequisites:
  109. A compiler (e.g., gcc with autotools) and gradle.
  110. On a Debian-like system the following should install everything you need for a
  111. minimal build:
  112. $ sudo apt-get install build-essential gradle
  113. When building from git sources, you will need to run the Gradle wrapper with the
  114. appropriate target, e.g. :
  115. ./gradlew buildAllExecutables
  116. SWIG bindings:
  117. --------------
  118. To generate language bindings from swig/libwebp.swig at least swig-1.3
  119. (http://www.swig.org) is required.
  120. Currently the following functions are mapped:
  121. Decode:
  122. WebPGetDecoderVersion
  123. WebPGetInfo
  124. WebPDecodeRGBA
  125. WebPDecodeARGB
  126. WebPDecodeBGRA
  127. WebPDecodeBGR
  128. WebPDecodeRGB
  129. Encode:
  130. WebPGetEncoderVersion
  131. WebPEncodeRGBA
  132. WebPEncodeBGRA
  133. WebPEncodeRGB
  134. WebPEncodeBGR
  135. WebPEncodeLosslessRGBA
  136. WebPEncodeLosslessBGRA
  137. WebPEncodeLosslessRGB
  138. WebPEncodeLosslessBGR
  139. See swig/README for more detailed build instructions.
  140. Java bindings:
  141. To build the swig-generated JNI wrapper code at least JDK-1.5 (or equivalent)
  142. is necessary for enum support. The output is intended to be a shared object /
  143. DLL that can be loaded via System.loadLibrary("webp_jni").
  144. Python bindings:
  145. To build the swig-generated Python extension code at least Python 2.6 is
  146. required. Python < 2.6 may build with some minor changes to libwebp.swig or the
  147. generated code, but is untested.
  148. Encoding tool:
  149. ==============
  150. The examples/ directory contains tools for encoding (cwebp) and
  151. decoding (dwebp) images.
  152. The easiest use should look like:
  153. cwebp input.png -q 80 -o output.webp
  154. which will convert the input file to a WebP file using a quality factor of 80
  155. on a 0->100 scale (0 being the lowest quality, 100 being the best. Default
  156. value is 75).
  157. You might want to try the -lossless flag too, which will compress the source
  158. (in RGBA format) without any loss. The -q quality parameter will in this case
  159. control the amount of processing time spent trying to make the output file as
  160. small as possible.
  161. A longer list of options is available using the -longhelp command line flag:
  162. > cwebp -longhelp
  163. Usage:
  164. cwebp [-preset <...>] [options] in_file [-o out_file]
  165. If input size (-s) for an image is not specified, it is
  166. assumed to be a PNG, JPEG, TIFF or WebP file.
  167. Options:
  168. -h / -help ............. short help
  169. -H / -longhelp ......... long help
  170. -q <float> ............. quality factor (0:small..100:big), default=75
  171. -alpha_q <int> ......... transparency-compression quality (0..100),
  172. default=100
  173. -preset <string> ....... preset setting, one of:
  174. default, photo, picture,
  175. drawing, icon, text
  176. -preset must come first, as it overwrites other parameters
  177. -z <int> ............... activates lossless preset with given
  178. level in [0:fast, ..., 9:slowest]
  179. -m <int> ............... compression method (0=fast, 6=slowest), default=4
  180. -segments <int> ........ number of segments to use (1..4), default=4
  181. -size <int> ............ target size (in bytes)
  182. -psnr <float> .......... target PSNR (in dB. typically: 42)
  183. -s <int> <int> ......... input size (width x height) for YUV
  184. -sns <int> ............. spatial noise shaping (0:off, 100:max), default=50
  185. -f <int> ............... filter strength (0=off..100), default=60
  186. -sharpness <int> ....... filter sharpness (0:most .. 7:least sharp), default=0
  187. -strong ................ use strong filter instead of simple (default)
  188. -nostrong .............. use simple filter instead of strong
  189. -sharp_yuv ............. use sharper (and slower) RGB->YUV conversion
  190. -partition_limit <int> . limit quality to fit the 512k limit on
  191. the first partition (0=no degradation ... 100=full)
  192. -pass <int> ............ analysis pass number (1..10)
  193. -crop <x> <y> <w> <h> .. crop picture with the given rectangle
  194. -resize <w> <h> ........ resize picture (after any cropping)
  195. -mt .................... use multi-threading if available
  196. -low_memory ............ reduce memory usage (slower encoding)
  197. -map <int> ............. print map of extra info
  198. -print_psnr ............ prints averaged PSNR distortion
  199. -print_ssim ............ prints averaged SSIM distortion
  200. -print_lsim ............ prints local-similarity distortion
  201. -d <file.pgm> .......... dump the compressed output (PGM file)
  202. -alpha_method <int> .... transparency-compression method (0..1), default=1
  203. -alpha_filter <string> . predictive filtering for alpha plane,
  204. one of: none, fast (default) or best
  205. -exact ................. preserve RGB values in transparent area, default=off
  206. -blend_alpha <hex> ..... blend colors against background color
  207. expressed as RGB values written in
  208. hexadecimal, e.g. 0xc0e0d0 for red=0xc0
  209. green=0xe0 and blue=0xd0
  210. -noalpha ............... discard any transparency information
  211. -lossless .............. encode image losslessly, default=off
  212. -near_lossless <int> ... use near-lossless image
  213. preprocessing (0..100=off), default=100
  214. -hint <string> ......... specify image characteristics hint,
  215. one of: photo, picture or graph
  216. -metadata <string> ..... comma separated list of metadata to
  217. copy from the input to the output if present.
  218. Valid values: all, none (default), exif, icc, xmp
  219. -short ................. condense printed message
  220. -quiet ................. don't print anything
  221. -version ............... print version number and exit
  222. -noasm ................. disable all assembly optimizations
  223. -v ..................... verbose, e.g. print encoding/decoding times
  224. -progress .............. report encoding progress
  225. Experimental Options:
  226. -jpeg_like ............. roughly match expected JPEG size
  227. -af .................... auto-adjust filter strength
  228. -pre <int> ............. pre-processing filter
  229. The main options you might want to try in order to further tune the
  230. visual quality are:
  231. -preset
  232. -sns
  233. -f
  234. -m
  235. Namely:
  236. * 'preset' will set up a default encoding configuration targeting a
  237. particular type of input. It should appear first in the list of options,
  238. so that subsequent options can take effect on top of this preset.
  239. Default value is 'default'.
  240. * 'sns' will progressively turn on (when going from 0 to 100) some additional
  241. visual optimizations (like: segmentation map re-enforcement). This option
  242. will balance the bit allocation differently. It tries to take bits from the
  243. "easy" parts of the picture and use them in the "difficult" ones instead.
  244. Usually, raising the sns value (at fixed -q value) leads to larger files,
  245. but with better quality.
  246. Typical value is around '75'.
  247. * 'f' option directly links to the filtering strength used by the codec's
  248. in-loop processing. The higher the value, the smoother the
  249. highly-compressed area will look. This is particularly useful when aiming
  250. at very small files. Typical values are around 20-30. Note that using the
  251. option -strong/-nostrong will change the type of filtering. Use "-f 0" to
  252. turn filtering off.
  253. * 'm' controls the trade-off between encoding speed and quality. Default is 4.
  254. You can try -m 5 or -m 6 to explore more (time-consuming) encoding
  255. possibilities. A lower value will result in faster encoding at the expense
  256. of quality.
  257. Decoding tool:
  258. ==============
  259. There is a decoding sample in examples/dwebp.c which will take
  260. a .webp file and decode it to a PNG image file (amongst other formats).
  261. This is simply to demonstrate the use of the API. You can verify the
  262. file test.webp decodes to exactly the same as test_ref.ppm by using:
  263. cd examples
  264. ./dwebp test.webp -ppm -o test.ppm
  265. diff test.ppm test_ref.ppm
  266. The full list of options is available using -h:
  267. > dwebp -h
  268. Usage: dwebp in_file [options] [-o out_file]
  269. Decodes the WebP image file to PNG format [Default]
  270. Use following options to convert into alternate image formats:
  271. -pam ......... save the raw RGBA samples as a color PAM
  272. -ppm ......... save the raw RGB samples as a color PPM
  273. -bmp ......... save as uncompressed BMP format
  274. -tiff ........ save as uncompressed TIFF format
  275. -pgm ......... save the raw YUV samples as a grayscale PGM
  276. file with IMC4 layout
  277. -yuv ......... save the raw YUV samples in flat layout
  278. Other options are:
  279. -version ..... print version number and exit
  280. -nofancy ..... don't use the fancy YUV420 upscaler
  281. -nofilter .... disable in-loop filtering
  282. -nodither .... disable dithering
  283. -dither <d> .. dithering strength (in 0..100)
  284. -alpha_dither use alpha-plane dithering if needed
  285. -mt .......... use multi-threading
  286. -crop <x> <y> <w> <h> ... crop output with the given rectangle
  287. -resize <w> <h> ......... scale the output (*after* any cropping)
  288. -flip ........ flip the output vertically
  289. -alpha ....... only save the alpha plane
  290. -incremental . use incremental decoding (useful for tests)
  291. -h ........... this help message
  292. -v ........... verbose (e.g. print encoding/decoding times)
  293. -quiet ....... quiet mode, don't print anything
  294. -noasm ....... disable all assembly optimizations
  295. Visualization tool:
  296. ===================
  297. There's a little self-serve visualization tool called 'vwebp' under the
  298. examples/ directory. It uses OpenGL to open a simple drawing window and show
  299. a decoded WebP file. It's not yet integrated in the automake build system, but
  300. you can try to manually compile it using the recommendations below.
  301. Usage: vwebp in_file [options]
  302. Decodes the WebP image file and visualize it using OpenGL
  303. Options are:
  304. -version ..... print version number and exit
  305. -noicc ....... don't use the icc profile if present
  306. -nofancy ..... don't use the fancy YUV420 upscaler
  307. -nofilter .... disable in-loop filtering
  308. -dither <int> dithering strength (0..100), default=50
  309. -noalphadither disable alpha plane dithering
  310. -mt .......... use multi-threading
  311. -info ........ print info
  312. -h ........... this help message
  313. KeyboardModule shortcuts:
  314. 'c' ................ toggle use of color profile
  315. 'i' ................ overlay file information
  316. 'd' ................ disable blending & disposal (debug)
  317. 'q' / 'Q' / ESC .... quit
  318. Building:
  319. ---------
  320. Prerequisites:
  321. 1) OpenGL & OpenGL Utility Toolkit (GLUT)
  322. Linux:
  323. $ sudo apt-get install freeglut3-dev mesa-common-dev
  324. Mac + XCode:
  325. - These libraries should be available in the OpenGL / GLUT frameworks.
  326. Windows:
  327. http://freeglut.sourceforge.net/index.php#download
  328. 2) (Optional) qcms (Quick Color Management System)
  329. i. Download qcms from Mozilla / Chromium:
  330. http://hg.mozilla.org/mozilla-central/file/0e7639e3bdfb/gfx/qcms
  331. http://src.chromium.org/viewvc/chrome/trunk/src/third_party/qcms
  332. ii. Build and archive the source files as libqcms.a / qcms.lib
  333. iii. Update makefile.unix / Makefile.vc
  334. a) Define WEBP_HAVE_QCMS
  335. b) Update include / library paths to reference the qcms directory.
  336. Build using makefile.unix / Makefile.vc:
  337. $ make -f makefile.unix examples/vwebp
  338. > nmake /f Makefile.vc CFG=release-static \
  339. ../obj/x64/release-static/bin/vwebp.exe
  340. Animation creation tool:
  341. ========================
  342. The utility 'img2webp' can turn a sequence of input images (PNG, JPEG, ...)
  343. into an animated WebP file. It offers fine control over duration, encoding
  344. modes, etc.
  345. Usage:
  346. img2webp [file-level options] [image files...] [per-frame options...]
  347. File-level options (only used at the start of compression):
  348. -min_size ............ minimize size
  349. -loop <int> .......... loop count (default: 0, = infinite loop)
  350. -kmax <int> .......... maximum number of frame between key-frames
  351. (0=only keyframes)
  352. -kmin <int> .......... minimum number of frame between key-frames
  353. (0=disable key-frames altogether)
  354. -mixed ............... use mixed lossy/lossless automatic mode
  355. -v ................... verbose mode
  356. -h ................... this help
  357. Per-frame options (only used for subsequent images input):
  358. -d <int> ............. frame duration in ms (default: 100)
  359. -lossless ........... use lossless mode (default)
  360. -lossy ... ........... use lossy mode
  361. -q <float> ........... quality
  362. -m <int> ............. method to use
  363. example: img2webp -loop 2 in0.png -lossy in1.jpg
  364. -d 80 in2.tiff -o out.webp
  365. Animated GIF conversion:
  366. ========================
  367. Animated GIF files can be converted to WebP files with animation using the
  368. gif2webp utility available under examples/. The files can then be viewed using
  369. vwebp.
  370. Usage:
  371. gif2webp [options] gif_file -o webp_file
  372. Options:
  373. -h / -help ............. this help
  374. -lossy ................. encode image using lossy compression
  375. -mixed ................. for each frame in the image, pick lossy
  376. or lossless compression heuristically
  377. -q <float> ............. quality factor (0:small..100:big)
  378. -m <int> ............... compression method (0=fast, 6=slowest)
  379. -min_size .............. minimize output size (default:off)
  380. lossless compression by default; can be
  381. combined with -q, -m, -lossy or -mixed
  382. options
  383. -kmin <int> ............ min distance between key frames
  384. -kmax <int> ............ max distance between key frames
  385. -f <int> ............... filter strength (0=off..100)
  386. -metadata <string> ..... comma separated list of metadata to
  387. copy from the input to the output if present
  388. Valid values: all, none, icc, xmp (default)
  389. -mt .................... use multi-threading if available
  390. -version ............... print version number and exit
  391. -v ..................... verbose
  392. -quiet ................. don't print anything
  393. Building:
  394. ---------
  395. With the libgif development files installed, gif2webp can be built using
  396. makefile.unix:
  397. $ make -f makefile.unix examples/gif2webp
  398. or using autoconf:
  399. $ ./configure --enable-everything
  400. $ make
  401. Comparison of animated images:
  402. ==============================
  403. Test utility anim_diff under examples/ can be used to compare two animated
  404. images (each can be GIF or WebP).
  405. Usage: anim_diff <image1> <image2> [options]
  406. Options:
  407. -dump_frames <folder> dump decoded frames in PAM format
  408. -min_psnr <float> ... minimum per-frame PSNR
  409. -raw_comparison ..... if this flag is not used, RGB is
  410. premultiplied before comparison
  411. Building:
  412. ---------
  413. With the libgif development files and a C++ compiler installed, anim_diff can
  414. be built using makefile.unix:
  415. $ make -f makefile.unix examples/anim_diff
  416. or using autoconf:
  417. $ ./configure --enable-everything
  418. $ make
  419. Encoding API:
  420. =============
  421. The main encoding functions are available in the header src/webp/encode.h
  422. The ready-to-use ones are:
  423. size_t WebPEncodeRGB(const uint8_t* rgb, int width, int height, int stride,
  424. float quality_factor, uint8_t** output);
  425. size_t WebPEncodeBGR(const uint8_t* bgr, int width, int height, int stride,
  426. float quality_factor, uint8_t** output);
  427. size_t WebPEncodeRGBA(const uint8_t* rgba, int width, int height, int stride,
  428. float quality_factor, uint8_t** output);
  429. size_t WebPEncodeBGRA(const uint8_t* bgra, int width, int height, int stride,
  430. float quality_factor, uint8_t** output);
  431. They will convert raw RGB samples to a WebP data. The only control supplied
  432. is the quality factor.
  433. There are some variants for using the lossless format:
  434. size_t WebPEncodeLosslessRGB(const uint8_t* rgb, int width, int height,
  435. int stride, uint8_t** output);
  436. size_t WebPEncodeLosslessBGR(const uint8_t* bgr, int width, int height,
  437. int stride, uint8_t** output);
  438. size_t WebPEncodeLosslessRGBA(const uint8_t* rgba, int width, int height,
  439. int stride, uint8_t** output);
  440. size_t WebPEncodeLosslessBGRA(const uint8_t* bgra, int width, int height,
  441. int stride, uint8_t** output);
  442. Of course in this case, no quality factor is needed since the compression
  443. occurs without loss of the input values, at the expense of larger output sizes.
  444. Advanced encoding API:
  445. ----------------------
  446. A more advanced API is based on the WebPConfig and WebPPicture structures.
  447. WebPConfig contains the encoding settings and is not tied to a particular
  448. picture.
  449. WebPPicture contains input data, on which some WebPConfig will be used for
  450. compression.
  451. The encoding flow looks like:
  452. -------------------------------------- BEGIN PSEUDO EXAMPLE
  453. #include <webp/encode.h>
  454. // Setup a config, starting form a preset and tuning some additional
  455. // parameters
  456. WebPConfig config;
  457. if (!WebPConfigPreset(&config, WEBP_PRESET_PHOTO, quality_factor))
  458. return 0; // version error
  459. }
  460. // ... additional tuning
  461. config.sns_strength = 90;
  462. config.filter_sharpness = 6;
  463. config_error = WebPValidateConfig(&config); // not mandatory, but useful
  464. // Setup the input data
  465. WebPPicture pic;
  466. if (!WebPPictureInit(&pic)) {
  467. return 0; // version error
  468. }
  469. pic.width = width;
  470. pic.height = height;
  471. // allocated picture of dimension width x height
  472. if (!WebPPictureAllocate(&pic)) {
  473. return 0; // memory error
  474. }
  475. // at this point, 'pic' has been initialized as a container,
  476. // and can receive the Y/U/V samples.
  477. // Alternatively, one could use ready-made import functions like
  478. // WebPPictureImportRGB(), which will take care of memory allocation.
  479. // In any case, past this point, one will have to call
  480. // WebPPictureFree(&pic) to reclaim memory.
  481. // Set up a byte-output write method. WebPMemoryWriter, for instance.
  482. WebPMemoryWriter wrt;
  483. WebPMemoryWriterInit(&wrt); // initialize 'wrt'
  484. pic.writer = MyFileWriter;
  485. pic.custom_ptr = my_opaque_structure_to_make_MyFileWriter_work;
  486. // Compress!
  487. int ok = WebPEncode(&config, &pic); // ok = 0 => error occurred!
  488. WebPPictureFree(&pic); // must be called independently of the 'ok' result.
  489. // output data should have been handled by the writer at that point.
  490. // -> compressed data is the memory buffer described by wrt.mem / wrt.size
  491. // deallocate the memory used by compressed data
  492. WebPMemoryWriterClear(&wrt);
  493. -------------------------------------- END PSEUDO EXAMPLE
  494. Decoding API:
  495. =============
  496. This is mainly just one function to call:
  497. #include "webp/decode.h"
  498. uint8_t* WebPDecodeRGB(const uint8_t* data, size_t data_size,
  499. int* width, int* height);
  500. Please have a look at the file src/webp/decode.h for the details.
  501. There are variants for decoding in BGR/RGBA/ARGB/BGRA order, along with
  502. decoding to raw Y'CbCr samples. One can also decode the image directly into a
  503. pre-allocated buffer.
  504. To detect a WebP file and gather the picture's dimensions, the function:
  505. int WebPGetInfo(const uint8_t* data, size_t data_size,
  506. int* width, int* height);
  507. is supplied. No decoding is involved when using it.
  508. Incremental decoding API:
  509. =========================
  510. In the case when data is being progressively transmitted, pictures can still
  511. be incrementally decoded using a slightly more complicated API. Decoder state
  512. is stored into an instance of the WebPIDecoder object. This object can be
  513. created with the purpose of decoding either RGB or Y'CbCr samples.
  514. For instance:
  515. WebPDecBuffer buffer;
  516. WebPInitDecBuffer(&buffer);
  517. buffer.colorspace = MODE_BGR;
  518. ...
  519. WebPIDecoder* idec = WebPINewDecoder(&buffer);
  520. As data is made progressively available, this incremental-decoder object
  521. can be used to decode the picture further. There are two (mutually exclusive)
  522. ways to pass freshly arrived data:
  523. either by appending the fresh bytes:
  524. WebPIAppend(idec, fresh_data, size_of_fresh_data);
  525. or by just mentioning the new size of the transmitted data:
  526. WebPIUpdate(idec, buffer, size_of_transmitted_buffer);
  527. Note that 'buffer' can be modified between each call to WebPIUpdate, in
  528. particular when the buffer is resized to accommodate larger data.
  529. These functions will return the decoding status: either VP8_STATUS_SUSPENDED if
  530. decoding is not finished yet or VP8_STATUS_OK when decoding is done. Any other
  531. status is an error condition.
  532. The 'idec' object must always be released (even upon an error condition) by
  533. calling: WebPDelete(idec).
  534. To retrieve partially decoded picture samples, one must use the corresponding
  535. method: WebPIDecGetRGB or WebPIDecGetYUVA.
  536. It will return the last displayable pixel row.
  537. Lastly, note that decoding can also be performed into a pre-allocated pixel
  538. buffer. This buffer must be passed when creating a WebPIDecoder, calling
  539. WebPINewRGB() or WebPINewYUVA().
  540. Please have a look at the src/webp/decode.h header for further details.
  541. Advanced Decoding API:
  542. ======================
  543. WebP decoding supports an advanced API which provides on-the-fly cropping and
  544. rescaling, something of great usefulness on memory-constrained environments like
  545. mobile phones. Basically, the memory usage will scale with the output's size,
  546. not the input's, when one only needs a quick preview or a zoomed in portion of
  547. an otherwise too-large picture. Some CPU can be saved too, incidentally.
  548. -------------------------------------- BEGIN PSEUDO EXAMPLE
  549. // A) Init a configuration object
  550. WebPDecoderConfig config;
  551. CHECK(WebPInitDecoderConfig(&config));
  552. // B) optional: retrieve the bitstream's features.
  553. CHECK(WebPGetFeatures(data, data_size, &config.input) == VP8_STATUS_OK);
  554. // C) Adjust 'config' options, if needed
  555. config.options.no_fancy_upsampling = 1;
  556. config.options.use_scaling = 1;
  557. config.options.scaled_width = scaledWidth();
  558. config.options.scaled_height = scaledHeight();
  559. // etc.
  560. // D) Specify 'config' output options for specifying output colorspace.
  561. // Optionally the external image decode buffer can also be specified.
  562. config.output.colorspace = MODE_BGRA;
  563. // Optionally, the config.output can be pointed to an external buffer as
  564. // well for decoding the image. This externally supplied memory buffer
  565. // should be big enough to store the decoded picture.
  566. config.output.u.RGBA.rgba = (uint8_t*) memory_buffer;
  567. config.output.u.RGBA.stride = scanline_stride;
  568. config.output.u.RGBA.size = total_size_of_the_memory_buffer;
  569. config.output.is_external_memory = 1;
  570. // E) Decode the WebP image. There are two variants w.r.t decoding image.
  571. // The first one (E.1) decodes the full image and the second one (E.2) is
  572. // used to incrementally decode the image using small input buffers.
  573. // Any one of these steps can be used to decode the WebP image.
  574. // E.1) Decode full image.
  575. CHECK(WebPDecode(data, data_size, &config) == VP8_STATUS_OK);
  576. // E.2) Decode image incrementally.
  577. WebPIDecoder* const idec = WebPIDecode(NULL, NULL, &config);
  578. CHECK(idec != NULL);
  579. while (bytes_remaining > 0) {
  580. VP8StatusCode status = WebPIAppend(idec, input, bytes_read);
  581. if (status == VP8_STATUS_OK || status == VP8_STATUS_SUSPENDED) {
  582. bytes_remaining -= bytes_read;
  583. } else {
  584. break;
  585. }
  586. }
  587. WebPIDelete(idec);
  588. // F) Decoded image is now in config.output (and config.output.u.RGBA).
  589. // It can be saved, displayed or otherwise processed.
  590. // G) Reclaim memory allocated in config's object. It's safe to call
  591. // this function even if the memory is external and wasn't allocated
  592. // by WebPDecode().
  593. WebPFreeDecBuffer(&config.output);
  594. -------------------------------------- END PSEUDO EXAMPLE
  595. Bugs:
  596. =====
  597. Please report all bugs to the issue tracker:
  598. https://bugs.chromium.org/p/webp
  599. Patches welcome! See this page to get started:
  600. http://www.webmproject.org/code/contribute/submitting-patches/
  601. Discuss:
  602. ========
  603. Email: webp-discuss@webmproject.org
  604. Web: http://groups.google.com/a/webmproject.org/group/webp-discuss