sane-wasm 0.4.0 → 0.6.0

package/README.md

@@ -10,86 +10,65 @@ Right now, it includes [all backends](http://www.sane-project.org/lists/sane-bac
 
 ## WebScan
 
-**Check [webscan.goncalomb.com](https://webscan.goncalomb.com/) for a demo of sane-wasm.** This is a React application that uses sane-wasm for document/image scanning directly in the browser. It exposes all scanning options to the user for full control.
+**Check [webscan.goncalomb.com](https://webscan.goncalomb.com/) ([source](https://github.com/goncalomb/webscan)) for a demo of sane-wasm.** This is a React application that uses sane-wasm for document/image scanning directly in the browser. It exposes all scanning options for full control.
 
 ## Usage
 
 The pre-compiled WebAssembly package for sane-wasm is published on NPM:
 
-https://www.npmjs.com/package/sane-wasm?activeTab=code
+<https://www.npmjs.com/package/sane-wasm>
 
-### For Web Environments (e.g. Webpack)
+### For Web environments (e.g. Webpack, Vite, etc.)
 
-```
-npm install -D sane-wasm
+```bash
+npm install sane-wasm
 ```
 
-The main .js will not be bundled with your application. A loader ([lib/loader.js](https://github.com/goncalomb/sane-wasm/blob/master/lib/loader.js)) is provided to automatically load the .js/.wasm files from a CDN ([jsdelivr.com](https://www.jsdelivr.com/)). You can configure the loader to serve the files from your server if you want.
+Cross-origin isolation ([COOP+COEP](https://web.dev/articles/coop-coep)) is required for [multithreading](https://emscripten.org/docs/porting/pthreads.html) which uses Web Workers and SharedArrayBuffer. This is not optional.
 
-See [examples/webpack/](https://github.com/goncalomb/sane-wasm/tree/master/examples/webpack) for a working example.
+See [examples/webpack/](./examples/webpack/) for a working example.
 
 ### For Node.js
 
-```
+```bash
 npm install sane-wasm usb
 ```
 
 The usb package ([node-usb](https://github.com/node-usb/node-usb)) is required to provide USB functionality.
 
-See [examples/node/](https://github.com/goncalomb/sane-wasm/tree/master/examples/node) for a working example.
-
-### As Git Submodule (not recommended) / Custom Build
-
-As an alternative, you can add sane-wasm as a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to your application and integrate `./build.sh` with your build process. This is not recommended as it relies on some magical/dubious code on `./build.sh` to make the build work.
-
-You can also just build sane-wasm independently and use the build artifacts...
-
-```
-<script src="build/libsane.js"></script>
-<script>
-    window.LibSANE().then(lib => {
-        // your code
-        console.log(lib.sane_init());
-    });
-</script>
-```
-
-```
-const { libsane } = require('./sane-wasm');
-libsane().then(lib => {
-    console.log(lib.sane_init());
-});
-```
-
-```
-import { libsane } from './sane-wasm';
-const lib = await libsane();
-console.log(lib.sane_init());
-```
+See [examples/node/](./examples/node/) for a working example.
 
 ## Building
 
-### SANE Only
+A pre-configured Docker image is used for building and debugging. Most `npm run ...` commands use Docker.
 
-Building requires [emscripten](https://github.com/emscripten-core/emscripten) and all the required tools to build the dependencies.
+### Build SANE and test page
 
-The preferred way is just to use the pre-configured Docker image:
+```bash
+git clone https://github.com/goncalomb/sane-wasm.git
+cd sane-wasm
+npm run debug
+```
 
-    git clone --recurse-submodules https://github.com/goncalomb/sane-wasm.git
-    cd sane-wasm
-    ./build.sh --with-docker --clean
+Check the test page at: <http://localhost:6931/libsane.html>.
 
-Start the test server with:
+### Other commands
 
-    ./build.sh --with-docker --no-build --emrun
+```bash
+npm run clean  # clean build artifacts and dependencies
+npm run build  # run full clean build (SANE + TypeScript)
+npm run debug  # run debug build (SANE only) and start the test server
+npm run emrun  # start the test server
+npm run test   # run the tests
+```
 
-Check the test page at: http://localhost:6931/libsane.html.
+### Non-Docker builds and `build.sh`
 
-#### build.sh
+Building without Docker is possible but untested. It requires [Emscripten](https://emscripten.org/) and all the tools to build the dependencies, see [Dockerfile](./Dockerfile).
 
-The `./build.sh` script has other options for debugging:
+The `./build.sh` script controls the build and has other options for debugging:
 
-```
+```text
 usage: build.sh [options]
   --with-docker  run with docker (preferred)
   --clean        clean 'deps' and 'build' directories
@@ -99,13 +78,11 @@ usage: build.sh [options]
   --shell        run debug shell (depends on --with-docker)
 ```
 
-### Full Build (SANE + TypeScript)
-
-To do a full build use `npm run build`.
-
 ## API
 
-Most of the SANE API is exposed as-is. Check the [SANE Standard](https://sane-project.gitlab.io/standard/index.html).
+API documentation is available at: [https://goncalomb.github.io/sane-wasm/](https://goncalomb.github.io/sane-wasm/modules.html).
+
+Most of the SANE API is exposed as-is, check the [SANE Standard](https://sane-project.gitlab.io/standard/index.html).
 
 Some safeguards are in place to avoid API misuse and prevent memory leaks. It's important to understand the SANE API and follow the [Code Flow](https://sane-project.gitlab.io/standard/api.html#code-flow) to avoid issues.
 
@@ -113,11 +90,23 @@ Some safeguards are in place to avoid API misuse and prevent memory leaks. It's
 
 The most important difference with the underlying SANE API is that **device handles are not exposed**. This means that `sane_open()` does not return a device handle. A single handle is managed by the internal code. This effectively means that **only one device can be accessed at a time**. This was a design decision made to simplify the API and prevent other issues.
 
-> Personally, I believe that this is an acceptable change, especially for WebAssembly where it may be easier to lose track of opened resources and crash the application. The SANE API is also somewhat unforgiving and building more safeguards around it (especially with multiple handles) is not worth the effort. Ultimately I don't see a use that requires more than one device open at a time. -goncalomb
+Other differences include:
+
+- function arguments and return values are adapted for javascript (see docs)
+- extra sane-wasm constants: `SANE_WASM_COMMIT`, `SANE_WASM_VERSION`, and `SANE_WASM_BACKENDS`
+- values of type `SANE_Fixed` are automatically converted to/from `Number`
+- extra `sane_get_state()` function exclusive to sane-wasm
+- `sane_control_option()` is split into 3 separate functions:
+  - `sane_control_option_get_value()`
+  - `sane_control_option_set_value()`
+  - `sane_control_option_set_auto()`
+- `sane_set_io_mode()` is not available on sane-wasm
+- `sane_get_select_fd()` is no available on sane-wasm
 
-### Documentation
+### Extra TypeScript classes (utilities)
 
-Check API documentation at: [goncalomb.github.io/sane-wasm/modules.html](https://goncalomb.github.io/sane-wasm/modules.html).
+- [src/options.ts](./src/options.ts) to manage scanner options
+- [src/readers.ts](./src/readers.ts) for image acquisition and decoding
 
 ## License
 

package/build/libsane.html

@@ -60,8 +60,35 @@
             <h2>Scan Result</h2>
             <canvas></canvas>
         </main>
-        <script async type="text/javascript" src="libsane.js"></script>
         <script>
+            function reloadWithDebug(on = true) {
+                location.hash = on ? JSON.stringify({
+                    debugSANE: true,
+                    debugUSB: true,
+                    debugFunctionCalls: true,
+                    debugTestDevices: 5,
+                }) : "";
+                location.reload();
+            }
+            const Module = LibSANE = {
+                sane: JSON.parse(decodeURIComponent(location.hash.substring(1)) || null) || {
+                    debugFunctionCalls: true,
+                    debugTestDevices: 3,
+                },
+            };
+            console.log("sane = ", Module.sane);
+            Module._promiseOnRuntimeInitialized = new Promise((resolve) => {
+                Module.onRuntimeInitialized = () => resolve(Module);
+            });
+            // the SCRIPT placeholder initializes the Module object
+        </script>
+        
+        <script type="module">
+          import initModule from "./libsane.js";
+          initModule(Module);
+        </script>
+        
+        <script type="module">
             (function() {
                 // util function to build the dom
                 const tree = (data, parent = document.createDocumentFragment()) => {
@@ -301,29 +328,9 @@
                     }
                 }
 
-                // reload with debug
-                function reloadWithDebug() {
-                    const sane = {
-                        debugSANE: true,
-                        debugUSB: true,
-                        debugFunctionCalls: true,
-                        debugTestDevices: 5,
-                    };
-                    location.hash = JSON.stringify(sane);
-                    location.reload();
-                }
-
                 // initialization
                 window.addEventListener("load", () => {
-                    const sane = JSON.parse(decodeURIComponent(location.hash.substring(1)) || null) || {
-                        debugFunctionCalls: true,
-                        debugTestDevices: 3,
-                    };
-                    console.log("sane = ", sane);
-                    window.LibSANE({ sane }).then(LibSANE => {
-                        // publish module to window
-                        window.LibSANE = LibSANE;
-                        // initialize
+                    Module._promiseOnRuntimeInitialized.then(LibSANE => {
                         const saneControls = document.querySelector("#sane-controls");
                         saneControls.innerHTML = "";
                         saneControls.append(tree([