1      __   __ ____ ____ ____     __  ____
2     /  \\/  \  _ \  _ \  _ \   (__)/  __\
3     \       /  __/ _  \  __/   _)  \_   \
4      \__\__/_____/____/_/     /____/____/
5 
6 Description:
7 ============
8 
9 This file describes the compilation of libwebp into a JavaScript decoder
10 using Emscripten and CMake.
11 
12  - install the Emscripten SDK following the procedure described at:
13    https://kripken.github.io/emscripten-site/docs/getting_started/downloads.html
14    After installation, you should have some global variable positioned to the
15    location of the SDK. In particular, $EMSCRIPTEN should point to the
16    top-level directory containing Emscripten tools.
17 
18  - make sure the file $EMSCRIPTEN/cmake/Modules/Platform/Emscripten.cmake is
19    accessible. This is the toolchain file used by CMake to invoke Emscripten.
20 
21  - configure the project 'WEBP_JS' with CMake using:
22 
23  cd webp_js && \
24  cmake -DWEBP_BUILD_WEBP_JS=ON \
25        -DEMSCRIPTEN_GENERATE_BITCODE_STATIC_LIBRARIES=1 \
26        -DCMAKE_TOOLCHAIN_FILE=$EMSCRIPTEN/cmake/Modules/Platform/Emscripten.cmake \
27        ../
28 
29  - compile webp.js using 'make'.
30 
31  - that's it! Upon completion, you should have the webp.js and
32    webp.js.mem files generated.
33 
34 The callable JavaScript function is WebPToSDL(), which decodes a raw WebP
35 bitstream into a canvas. See webp_js/index.html for a simple usage sample
36 (see below for instructions).
37 
38 Demo HTML page:
39 ===============
40 
41    The HTML page webp_js/index.html requires an HTTP server to serve the WebP
42    image example. It's easy to just use Python for that.
43 
44 cd webp_js && python -m SimpleHTTPServer 8080
45 
46 and then navigate to http://localhost:8080 in your favorite browser.
47 
48 
49 Web-Assembly (WASM) version:
50 ============================
51 
52   CMakeLists.txt is configured to build the WASM version when using
53   the option WEBP_BUILD_WEBP_JS=ON. The compilation step will assemble
54   the files 'webp_wasm.js', 'webp_wasm.wasm' in the webp_js/ directory.
55   See webp_js/index_wasm.html for a simple demo page using the WASM version
56   of the library.
57 
58   You will need a fairly recent version of Emscripten (at least 1.37.8) and of
59   your WASM-enabled browser to run this version. Consider it very experimental!
60 
61 Caveat:
62 =======
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 "Unsupported:   %516 = bitcast <8 x i16> %481 to i128
71  LLVM ERROR: BitCast Instruction not yet supported for integer types larger than 64 bits"
72 
73     The corresponding Emscripten bug is at:
74     https://github.com/kripken/emscripten/issues/3788
75 
76     Therefore, SSE2 optimization is currently disabled in CMakeLists.txt.
77