• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# WebP JavaScript decoder
2
3```
4 __   __ ____ ____ ____     __  ____
5/  \\/  \  _ \  _ \  _ \   (__)/  __\
6\       /  __/ _  \  __/   _)  \_   \
7 \__\__/_____/____/_/     /____/____/
8```
9
10This file describes the compilation of libwebp into a JavaScript decoder using
11Emscripten and CMake.
12
13-   install the Emscripten SDK following the procedure described at:
14    https://emscripten.org/docs/getting_started/downloads.html#installation-instructions-using-the-emsdk-recommended
15    After installation, you should have some global variable positioned to the
16    location of the SDK. In particular, $EMSDK should point to the top-level
17    directory containing Emscripten tools.
18
19-   configure the project 'WEBP_JS' with CMake using:
20
21    ```shell
22    cd webp_js && \
23    emcmake cmake -DWEBP_BUILD_WEBP_JS=ON \
24          ../
25    ```
26
27-   compile webp.js using 'emmake make'.
28
29-   that's it! Upon completion, you should have the 'webp.js', 'webp.js.mem',
30    'webp_wasm.js' and 'webp_wasm.wasm' files generated.
31
32The callable JavaScript function is WebPToSDL(), which decodes a raw WebP
33bitstream into a canvas. See webp_js/index.html for a simple usage sample (see
34below for instructions).
35
36## Demo HTML page
37
38The HTML page webp_js/index.html requires the built files 'webp.js' and
39'webp.js.mem' to be copied to webp_js/. An HTTP server to serve the WebP image
40example is also needed. With Python, just run:
41
42```shell
43cd webp_js && python3 -m http.server 8080
44```
45
46and then navigate to http://localhost:8080 in your favorite browser.
47
48## Web-Assembly (WASM) version:
49
50CMakeLists.txt is configured to build the WASM version when using the option
51WEBP_BUILD_WEBP_JS=ON. The compilation step will assemble the files
52'webp_wasm.js' and 'webp_wasm.wasm' that you then need to copy to the webp_js/
53directory.
54
55See webp_js/index_wasm.html for a simple demo page using the WASM version of the
56library.
57
58You will need a fairly recent version of Emscripten (at least 2.0.18,
59latest-upstream is recommended) and of your WASM-enabled browser to run this
60version.
61
62## Caveats
63
64-   First decoding using the library is usually slower, due to just-in-time
65    compilation.
66
67-   Some versions of llvm produce the following compile error when SSE2 is
68    enabled.
69
70    ```
71    "Unsupported:   %516 = bitcast <8 x i16> %481 to i128
72    LLVM ERROR: BitCast Instruction not yet supported for integer types larger than 64 bits"
73    ```
74
75    The corresponding Emscripten bug is at:
76    https://github.com/kripken/emscripten/issues/3788
77
78    Therefore, SSE2 optimization is currently disabled in CMakeLists.txt.
79
80-   If WEBP_ENABLE_SIMD is set to 1 the JavaScript version (webp.js) will be
81    disabled as wasm2js does not support SIMD.
82