Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 38 ยท Projects and Practice

Project: Image Filter in WebAssembly

Build an image filter with WebAssembly - RGBA pixel memory, a grayscale and invert module, zero-copy typed-array views, a JavaScript reference, tests, benchmark and the Canvas wiring for the browser.

Image processing is the textbook job for WebAssembly: a big array of small numbers, the same simple operation applied to every element, no DOM access needed in the inner loop. In this project you build a small filter library with two operations, invert and grayscale, write a plain JavaScript reference to check it against, test it, benchmark it, and then see how to connect it to a <canvas> in a browser.

Everything the project needs to run here is provided: the module is hand-assembled, and the "image" is a generated pixel buffer, so every output is deterministic. The last section shows the browser wiring as read-only code, since a canvas does not exist in the runner.

The plan

flowchart LR
  A["Canvas getImageData()"] --> B["Copy RGBA bytes into wasm memory"]
  B --> C["wasm: grayscale(ptr, pixels)"]
  C --> D["Read result through a typed-array view"]
  D --> E["Canvas putImageData()"]

One copy in, a tight loop in wasm, one copy out.

Project outline

Pixels 4 bytes each: R, G, B, A.
Module invert and grayscale loops.
Tests Compare with a JS reference.
Benchmark Many runs, median time.

Then wire it to a canvas.

1 / 2

Step 1: understand the memory layout

An RGBA image is a flat sequence of bytes: R G B A R G B A ..., row by row. A pixel is 4 bytes, so an image of w by h pixels is w * h * 4 bytes. In JavaScript, ImageData.data is a Uint8ClampedArray with exactly this layout. In the module, ptr is the address of the first byte, and pixel i starts at ptr + 4 * i.

The module's two exports, written in the text format:

WAT
(func (export "invert") (param $ptr i32) (param $pixels i32) ...)     ;; R,G,B = 255 - value, alpha untouched
(func (export "grayscale") (param $ptr i32) (param $pixels i32) ...)  ;; Y = (77 R + 150 G + 29 B) >> 8

The grayscale formula is an integer version of the weighted brightness average (green counts most, blue least, because of how the eye responds). The weights 77, 150 and 29 add up to 256, so dividing by 256 is a right shift by 8, which needs no floating point and no division.

Step 2: a reference in JavaScript

A reference implementation is the best test you can have. It is slow and obviously correct, so the optimized version must match it exactly.

JavaScript
function invertRef(rgba) {
  for (let i = 0; i < rgba.length; i += 4) {
    rgba[i] = 255 - rgba[i];
    rgba[i + 1] = 255 - rgba[i + 1];
    rgba[i + 2] = 255 - rgba[i + 2];
  }
}
function grayscaleRef(rgba) {
  for (let i = 0; i < rgba.length; i += 4) {
    const y = (77 * rgba[i] + 150 * rgba[i + 1] + 29 * rgba[i + 2]) >> 8;
    rgba[i] = rgba[i + 1] = rgba[i + 2] = y;
  }
}

Step 3: run the module and test it

The next program builds an 8 by 8 gradient image (red increases left to right, green top to bottom, blue is a diagonal), copies it into wasm memory, runs both filters and asserts that they match the reference byte for byte. It also prints the grayscale result as ASCII art so you can see the effect.

Node.js Filter an 8x8 image and check against the reference

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A few points worth noticing. The view new Uint8Array(wasm.memory.buffer, PTR, image.length) is created right before use, so it cannot be stale. The filter is called once with the pixel count, not once per pixel. Alpha is never touched. And the test compares the whole buffer with the reference, so an off-by-one in the module would show up immediately.

Step 4: benchmark honestly

The module has a single 64 KiB memory page, so the benchmark uses a 120 by 120 image (57,600 bytes), which fits. The test repeats the filter many times to get measurable durations, uses a warm-up, and reports the median of several samples.

Node.js Wasm versus JavaScript on 120 by 120 pixels

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The three lines tell the story you should expect from real projects: the pure loop is fast, but if you copy the image in and out for every call, the copies can cost as much as the work itself. For a video filter, keep one wasm-side buffer, write each frame into it, and read the result straight back out through the same view.

Step 5: connect it to a canvas in a browser

This part cannot run in the runner, but it is short. The key line is ctx.getImageData, which gives you the pixel bytes, and ctx.putImageData, which draws them back.

HTML
<canvas id="c" width="320" height="240"></canvas>
<button id="gray">Grayscale</button> <button id="inv">Invert</button>
<script type="module">
  const { instance } = await WebAssembly.instantiateStreaming(fetch('/filters.wasm'));
  const wasm = instance.exports;

  const canvas = document.getElementById('c');
  const ctx = canvas.getContext('2d');
  const img = new Image();
  img.src = '/photo.jpg';
  await img.decode();
  ctx.drawImage(img, 0, 0, canvas.width, canvas.height);

  function apply(filter) {
    const frame = ctx.getImageData(0, 0, canvas.width, canvas.height);
    const pixels = canvas.width * canvas.height;
    // Make sure memory is big enough: 4 bytes per pixel.
    const needed = pixels * 4;
    const have = wasm.memory.buffer.byteLength;
    if (needed > have) wasm.memory.grow(Math.ceil((needed - have) / 65536));
    const view = new Uint8Array(wasm.memory.buffer, 0, needed);   // create AFTER growing
    view.set(frame.data);
    wasm[filter](0, pixels);
    frame.data.set(view);
    ctx.putImageData(frame, 0, 0);
  }
  document.getElementById('gray').onclick = () => apply('grayscale');
  document.getElementById('inv').onclick = () => apply('invert');
</script>

Things to remember in a real page: image data from another origin taints the canvas and getImageData throws a SecurityError unless the image is served with CORS headers; heavy filters belong in a Web Worker with OffscreenCanvas (see Bundlers and Loading Strategies); and you must create the typed-array view after any memory.grow.

Ideas to extend the project

  1. Add a brightness(ptr, pixels, amount) filter with clamping to 0 to 255.
  2. Add a box blur (average of a 3 by 3 neighborhood) that needs width and height as arguments.
  3. Use SIMD to process four pixels at a time, with a baseline fallback (see SIMD and Threads).
  4. Add a histogram function that fills 256 counters in memory.
  5. Compile the same filters from C or Rust and compare size and speed (see Compiling C to WebAssembly with Emscripten).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How many bytes does a 10 by 5 RGBA image occupy?

    10 x 5 = 50 pixels, and each pixel is 4 bytes (R, G, B, A), so 200 bytes.
  2. 2. Why divide by 256 using a shift (>> 8) in the grayscale formula?

    77 + 150 + 29 = 256, so the weighted sum divided by 256 stays within 0 to 255, and >> 8 does the division with no floating point.
  3. 3. What is the best use of a JavaScript reference implementation?

    A slow but obviously correct version is the ideal oracle for testing the optimized one.
  4. 4. When must you create the Uint8Array view over wasm memory when images may need more memory?

    Growth replaces the underlying ArrayBuffer, so views made before it have zero length.

Summary

  • An RGBA image is a flat byte array; process it in one call with a pointer and a pixel count.
  • Write a plain reference implementation and compare the wasm output byte for byte.
  • Use zero-copy views over memory.buffer, but create them after any growth, and avoid per-call copies in hot paths.
  • Benchmark with warm-up, repeats and the median; include copy costs.
  • In the browser connect with getImageData and putImageData, mind CORS tainting, and use workers for heavy filters.

Next: Project: Prime Sieve and Benchmark Harness