@sythos/js_barcode_universal 0.1.0

package/src/render/image-data.js

@@ -0,0 +1,125 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Raster output as ImageData, and 2D-canvas drawing.
+ *
+ * @module render/image-data
+ */
+
+import { normalizeOptions, parseColor } from './options.js';
+
+/**
+ * Render to an `ImageData`-shaped object.
+ *
+ * A plain object rather than a real `ImageData`, so this works in Node and in
+ * workers without a DOM. It is accepted directly by `ctx.putImageData` in the
+ * browser, and by this library's own reader.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix
+ * @param {import('./options.js').RenderOptions} [options]
+ * @returns {{data: Uint8ClampedArray, width: number, height: number}}
+ */
+export function toImageData(matrix, options = {}) {
+  const opts = normalizeOptions(matrix, options);
+  const { scale, source, pixelWidth, pixelHeight } = opts;
+
+  const dark = parseColor(opts.dark);
+  const light = parseColor(opts.light);
+  const data = new Uint8ClampedArray(pixelWidth * pixelHeight * 4);
+
+  // Fill one scanline per module row, then copy it `scale` times. Barcodes are
+  // wide and repetitive, so this is markedly faster than a per-pixel loop.
+  const line = new Uint8ClampedArray(pixelWidth * 4);
+
+  for (let my = 0; my < source.height; my++) {
+    for (let mx = 0; mx < source.width; mx++) {
+      const colour = source.get(mx, my) ? dark : light;
+      const start = mx * scale * 4;
+      for (let px = 0; px < scale; px++) {
+        const p = start + px * 4;
+        line[p] = colour[0];
+        line[p + 1] = colour[1];
+        line[p + 2] = colour[2];
+        line[p + 3] = colour[3];
+      }
+    }
+    for (let py = 0; py < scale; py++) {
+      data.set(line, ((my * scale + py) * pixelWidth) * 4);
+    }
+  }
+
+  return { data, width: pixelWidth, height: pixelHeight };
+}
+
+/**
+ * Draw into a canvas using its 2D context.
+ *
+ * This is the universal fallback: every browser that runs JavaScript at all
+ * has a 2D context, including every iOS Safari version.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix
+ * @param {HTMLCanvasElement | OffscreenCanvas} canvas
+ * @param {import('./options.js').RenderOptions} [options]
+ * @returns {boolean} True when it drew.
+ */
+export function toCanvas(matrix, canvas, options = {}) {
+  const opts = normalizeOptions(matrix, options);
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return false;
+
+  canvas.width = opts.pixelWidth;
+  canvas.height = opts.pixelHeight;
+
+  // Draw with fillRect rather than putImageData: it respects the canvas's
+  // alpha compositing, so a transparent `light` leaves the page showing
+  // through instead of punching a hole.
+  const [, , , lightAlpha] = parseColor(opts.light);
+  if (lightAlpha > 0) {
+    ctx.fillStyle = opts.light;
+    ctx.fillRect(0, 0, opts.pixelWidth, opts.pixelHeight);
+  } else {
+    ctx.clearRect(0, 0, opts.pixelWidth, opts.pixelHeight);
+  }
+
+  ctx.fillStyle = opts.dark;
+  const { source, scale } = opts;
+  for (let y = 0; y < source.height; y++) {
+    let x = 0;
+    while (x < source.width) {
+      if (!source.get(x, y)) { x++; continue; }
+      let run = 1;
+      while (x + run < source.width && source.get(x + run, y)) run++;
+      ctx.fillRect(x * scale, y * scale, run * scale, scale);
+      x += run;
+    }
+  }
+  return true;
+}

package/src/render/index.js

@@ -0,0 +1,130 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Output backends.
+ *
+ * ## On GPU acceleration — read this before assuming what it does
+ *
+ * The WebGL2 and WebGPU backends accelerate **drawing** a barcode, not
+ * **computing** one. That distinction is worth stating plainly, because "GPU
+ * barcode generation" naturally sounds like the latter.
+ *
+ * Encoding is sequential integer work: Reed-Solomon polynomial division, mask
+ * penalty scoring, bit placement along a zig-zag path. Each step depends on the
+ * one before it, which is precisely the shape a GPU cannot exploit. A complete
+ * QR encode takes well under a millisecond on the CPU — less time than it takes
+ * to dispatch a compute shader and read the result back. Moving it to the GPU
+ * would make it slower, not faster, and no amount of engineering changes that.
+ *
+ * What the GPU genuinely helps with:
+ *
+ *   - **Drawing** large symbols, or many symbols per frame, straight into a
+ *     canvas without a CPU-side pixel buffer.
+ *   - **Reading**, where per-frame greyscale conversion and block statistics
+ *     over a 1080p or 4K camera image are the real bottleneck and are
+ *     embarrassingly parallel.
+ *
+ * So: encoding stays on the CPU because that is the correct engineering answer,
+ * not because of a missing feature.
+ *
+ * @module render
+ */
+
+export { toSVG, toSVGDataURI } from './svg.js';
+export { toImageData, toCanvas } from './image-data.js';
+export { toPNG, toPNGDataURI, deflateStored } from './png.js';
+export { isWebGL2Available, renderToCanvasWebGL } from './webgl.js';
+export { isWebGPUAvailable, renderToCanvasWebGPU } from './webgpu.js';
+export { normalizeOptions, parseColor } from './options.js';
+
+import { toCanvas } from './image-data.js';
+import { isWebGL2Available, renderToCanvasWebGL } from './webgl.js';
+import { isWebGPUAvailable, renderToCanvasWebGPU } from './webgpu.js';
+
+/**
+ * Draw into a canvas using the best backend available.
+ *
+ * Tries WebGL2, then the 2D context. The 2D path is always available, so this
+ * never fails on a browser that can run the library at all — including every
+ * version of Safari on iOS.
+ *
+ * WebGPU is not reachable from here, and cannot be: obtaining an adapter is
+ * asynchronous, so a synchronous function can never wait for one. Use
+ * `renderToCanvasAutoAsync` to include it. This one stays synchronous because
+ * it is the documented signature and callers rely on the returned backend name
+ * being available immediately.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix
+ * @param {HTMLCanvasElement | OffscreenCanvas} canvas
+ * @param {import('./options.js').RenderOptions & {backend?: 'auto'|'webgl2'|'2d'}} [options]
+ * @returns {{backend: 'webgl2' | '2d' | 'none'}}
+ */
+export function renderToCanvasAuto(matrix, canvas, options = {}) {
+  const preferred = options.backend ?? 'auto';
+
+  if ((preferred === 'auto' || preferred === 'webgl2') && isWebGL2Available()) {
+    if (renderToCanvasWebGL(matrix, canvas, options)) return { backend: 'webgl2' };
+  }
+  if (toCanvas(matrix, canvas, options)) return { backend: '2d' };
+  return { backend: 'none' };
+}
+
+/**
+ * Draw into a canvas using the best backend available, including WebGPU.
+ *
+ * Tries WebGPU, then WebGL2, then the 2D context, and returns the name of the
+ * one that drew.
+ *
+ * Each backend is *probed* before the canvas is handed to it. That ordering is
+ * deliberate: a canvas can only ever have one kind of context, so committing it
+ * to WebGPU and failing afterwards would leave it unable to fall back to
+ * WebGL2 or 2D. The probes use throwaway objects of their own, so the caller's
+ * canvas is only touched by a backend that is already known to work.
+ *
+ * @param {import('../core/bit-matrix.js').BitMatrix} matrix
+ * @param {HTMLCanvasElement | OffscreenCanvas} canvas
+ * @param {import('./options.js').RenderOptions & {backend?: 'auto'|'webgpu'|'webgl2'|'2d'}} [options]
+ * @returns {Promise<{backend: 'webgpu' | 'webgl2' | '2d' | 'none'}>}
+ */
+export async function renderToCanvasAutoAsync(matrix, canvas, options = {}) {
+  const preferred = options.backend ?? 'auto';
+
+  if (preferred === 'auto' || preferred === 'webgpu') {
+    if (await isWebGPUAvailable()) {
+      if (await renderToCanvasWebGPU(matrix, canvas, options)) return { backend: 'webgpu' };
+    }
+  }
+  if ((preferred === 'auto' || preferred === 'webgl2') && isWebGL2Available()) {
+    if (renderToCanvasWebGL(matrix, canvas, options)) return { backend: 'webgl2' };
+  }
+  if (toCanvas(matrix, canvas, options)) return { backend: '2d' };
+  return { backend: 'none' };
+}

package/src/render/options.js

@@ -0,0 +1,160 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Shared render options, normalised once so every backend agrees.
+ *
+ * @module render/options
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+
+/**
+ * @typedef {object} RenderOptions
+ * @property {number} [scale] Pixels per module. Default 8.
+ * @property {number} [margin] Quiet-zone modules on every side. Default 4.
+ * @property {string} [dark] Colour of set modules. Default '#000000'.
+ * @property {string} [light] Colour of clear modules, or 'none' for transparent.
+ * @property {number} [barHeight] For 1D symbols: total bar height in pixels.
+ */
+
+/**
+ * Expand and pad the matrix, and resolve every dimension.
+ *
+ * Linear symbols arrive one module tall. They are stretched to `barHeight`
+ * *before* the quiet zone is applied, so the margin ends up uniform on all
+ * four sides — padding first would leave a quiet zone one module tall against
+ * bars a hundred pixels tall, which no scanner would accept.
+ *
+ * @param {BitMatrix} matrix
+ * @param {RenderOptions} options
+ */
+export function normalizeOptions(matrix, options = {}) {
+  const scale = Math.max(1, Math.floor(options.scale ?? 8));
+  const margin = Math.max(0, Math.floor(options.margin ?? 4));
+  const dark = options.dark ?? '#000000';
+  const light = options.light ?? '#ffffff';
+  const barHeight = options.barHeight ?? null;
+
+  let base = matrix;
+  const is1D = matrix.height === 1;
+
+  if (is1D) {
+    // Default to a bar height that stays scannable: tall enough that a laser
+    // crossing at a slight angle still passes through the whole symbol.
+    const targetPixels = barHeight ?? Math.max(40, Math.round(matrix.width * scale * 0.15));
+    const rows = Math.max(1, Math.round(targetPixels / scale));
+    base = new BitMatrix(matrix.width, rows);
+    for (let x = 0; x < matrix.width; x++) {
+      if (!matrix.get(x, 0)) continue;
+      for (let y = 0; y < rows; y++) base.set(x, y);
+    }
+  }
+
+  const source = margin > 0 ? base.withMargin(margin) : base;
+
+  return {
+    scale,
+    margin,
+    dark,
+    light,
+    is1D,
+    source,
+    rowHeight: scale,
+    pixelWidth: source.width * scale,
+    pixelHeight: source.height * scale,
+  };
+}
+
+/**
+ * Parse a CSS colour into RGBA bytes.
+ *
+ * Supports the forms a barcode actually needs: #rgb, #rgba, #rrggbb,
+ * #rrggbbaa, rgb(), rgba(), plus 'none' and 'transparent'.
+ *
+ * @param {string} colour
+ * @returns {[number, number, number, number]}
+ */
+export function parseColor(colour) {
+  const value = String(colour).trim().toLowerCase();
+
+  if (value === 'none' || value === 'transparent') return [0, 0, 0, 0];
+  if (value === 'white') return [255, 255, 255, 255];
+  if (value === 'black') return [0, 0, 0, 255];
+
+  if (value[0] === '#') {
+    const hex = value.slice(1);
+    const expand = (c) => parseInt(c + c, 16);
+    if (hex.length === 3) {
+      return [expand(hex[0]), expand(hex[1]), expand(hex[2]), 255];
+    }
+    if (hex.length === 4) {
+      return [expand(hex[0]), expand(hex[1]), expand(hex[2]), expand(hex[3])];
+    }
+    if (hex.length === 6) {
+      return [
+        parseInt(hex.slice(0, 2), 16),
+        parseInt(hex.slice(2, 4), 16),
+        parseInt(hex.slice(4, 6), 16),
+        255,
+      ];
+    }
+    if (hex.length === 8) {
+      return [
+        parseInt(hex.slice(0, 2), 16),
+        parseInt(hex.slice(2, 4), 16),
+        parseInt(hex.slice(4, 6), 16),
+        parseInt(hex.slice(6, 8), 16),
+      ];
+    }
+  }
+
+  const fn = value.match(/^rgba?\(([^)]+)\)$/);
+  if (fn) {
+    const parts = fn[1].split(/[,/\s]+/).filter(Boolean);
+    const channel = (s) => (s.endsWith('%')
+      ? Math.round((parseFloat(s) / 100) * 255)
+      : Math.round(parseFloat(s)));
+    const r = channel(parts[0]);
+    const g = channel(parts[1]);
+    const b = channel(parts[2]);
+    let a = 255;
+    if (parts.length > 3) {
+      a = parts[3].endsWith('%')
+        ? Math.round((parseFloat(parts[3]) / 100) * 255)
+        : Math.round(parseFloat(parts[3]) * 255);
+    }
+    return [r, g, b, a];
+  }
+
+  // Unrecognised: fall back to opaque black rather than throwing, so an
+  // unusual colour never costs someone a barcode.
+  return [0, 0, 0, 255];
+}