@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/av1/decode/decode_palette.js

@@ -0,0 +1,442 @@
+import { clamp } from "../../../../core/math/clamp.js";
+import {
+    DC_PRED,
+    MI_SIZE,
+    PALETTE_COLORS,
+    PALETTE_NUM_NEIGHBORS
+} from "../tables/av1_symbols.js";
+import { MI_HEIGHT_LOG2, MI_WIDTH_LOG2 } from "../tables/block_tables.js";
+import { BLOCK_HEIGHT, BLOCK_WIDTH } from "../tables/derived_block_tables.js";
+import { PALETTE_COLOR_CONTEXT, PALETTE_COLOR_HASH_MULTIPLIERS } from "../tables/prediction_tables.js";
+import { ceil_log2 } from "../util/ceil_log2.js";
+import { MAX_PALETTE_SIZE } from "./Av1FrameContext.js";
+
+/**
+ * Read a block's palettes.
+ *
+ * Colours are coded as a mixture of cache hits — colours reused from the blocks above and to the
+ * left — a literal, and then deltas whose width shrinks as the colours climb towards the top of the
+ * range. The V plane is the odd one out: its colours may be delta-coded with a sign and wrap around
+ * the range, because chroma has no reason to be monotonic.
+ *
+ * @param {Av1FrameContext} ctx
+ * @see AV1 spec 5.11.46 "Palette mode info syntax"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function read_palette_mode_info(ctx) {
+    const reader = ctx.reader;
+    const cdf = ctx.cdf;
+
+    const bit_depth = ctx.bit_depth;
+    const max_value = (1 << bit_depth) - 1;
+
+    const bsize_ctx = MI_WIDTH_LOG2[ctx.mi_size] + MI_HEIGHT_LOG2[ctx.mi_size] - 2;
+
+    if (ctx.y_mode === DC_PRED) {
+        let ctx_y = 0;
+
+        if (ctx.avail_u === 1 && ctx.palette_sizes[0 * ctx.mi_stride * ctx.mi_rows + (ctx.mi_row - 1) * ctx.mi_stride + ctx.mi_col] > 0) {
+            ctx_y += 1;
+        }
+
+        if (ctx.avail_l === 1 && ctx.palette_sizes[0 * ctx.mi_stride * ctx.mi_rows + ctx.mi_row * ctx.mi_stride + ctx.mi_col - 1] > 0) {
+            ctx_y += 1;
+        }
+
+        const has_palette_y = reader.read_symbol(cdf.palette_y_mode, (bsize_ctx * 3 + ctx_y) * 3, 2);
+
+        if (has_palette_y === 1) {
+            ctx.palette_size_y = reader.read_symbol(cdf.palette_y_size, bsize_ctx * 8, 7) + 2;
+
+            const cache_count = build_palette_cache(ctx, 0);
+
+            let idx = 0;
+
+            for (let i = 0; i < cache_count && idx < ctx.palette_size_y; i++) {
+                if (reader.read_bool() === 1) {
+                    ctx.palette_colors_y[idx] = ctx.palette_cache[i];
+                    idx++;
+                }
+            }
+
+            if (idx < ctx.palette_size_y) {
+                ctx.palette_colors_y[idx] = reader.read_literal(bit_depth);
+                idx++;
+            }
+
+            let palette_bits = 0;
+
+            if (idx < ctx.palette_size_y) {
+                palette_bits = (bit_depth - 3) + reader.read_literal(2);
+            }
+
+            while (idx < ctx.palette_size_y) {
+                const delta = reader.read_literal(palette_bits) + 1;
+
+                ctx.palette_colors_y[idx] = clamp(ctx.palette_colors_y[idx - 1] + delta, 0, max_value);
+
+                const range = (1 << bit_depth) - ctx.palette_colors_y[idx] - 1;
+
+                palette_bits = Math.min(palette_bits, ceil_log2(range));
+
+                idx++;
+            }
+
+            sort_palette(ctx.palette_colors_y, ctx.palette_size_y);
+        }
+    }
+
+    if (ctx.has_chroma === 1 && ctx.uv_mode === DC_PRED) {
+        const has_palette_uv = reader.read_symbol(cdf.palette_uv_mode, (ctx.palette_size_y > 0 ? 1 : 0) * 3, 2);
+
+        if (has_palette_uv === 1) {
+            ctx.palette_size_uv = reader.read_symbol(cdf.palette_uv_size, bsize_ctx * 8, 7) + 2;
+
+            const cache_count = build_palette_cache(ctx, 1);
+
+            let idx = 0;
+
+            for (let i = 0; i < cache_count && idx < ctx.palette_size_uv; i++) {
+                if (reader.read_bool() === 1) {
+                    ctx.palette_colors_u[idx] = ctx.palette_cache[i];
+                    idx++;
+                }
+            }
+
+            if (idx < ctx.palette_size_uv) {
+                ctx.palette_colors_u[idx] = reader.read_literal(bit_depth);
+                idx++;
+            }
+
+            let palette_bits = 0;
+
+            if (idx < ctx.palette_size_uv) {
+                palette_bits = (bit_depth - 3) + reader.read_literal(2);
+            }
+
+            while (idx < ctx.palette_size_uv) {
+                const delta = reader.read_literal(palette_bits);
+
+                ctx.palette_colors_u[idx] = clamp(ctx.palette_colors_u[idx - 1] + delta, 0, max_value);
+
+                const range = (1 << bit_depth) - ctx.palette_colors_u[idx];
+
+                palette_bits = Math.min(palette_bits, ceil_log2(range));
+
+                idx++;
+            }
+
+            sort_palette(ctx.palette_colors_u, ctx.palette_size_uv);
+
+            if (reader.read_bool() === 1) {
+                const max_val = 1 << bit_depth;
+
+                const bits = (bit_depth - 4) + reader.read_literal(2);
+
+                ctx.palette_colors_v[0] = reader.read_literal(bit_depth);
+
+                for (let i = 1; i < ctx.palette_size_uv; i++) {
+                    let delta = reader.read_literal(bits);
+
+                    if (delta !== 0 && reader.read_bool() === 1) {
+                        delta = -delta;
+                    }
+
+                    let value = ctx.palette_colors_v[i - 1] + delta;
+
+                    if (value < 0) {
+                        value += max_val;
+                    }
+
+                    if (value >= max_val) {
+                        value -= max_val;
+                    }
+
+                    ctx.palette_colors_v[i] = clamp(value, 0, max_value);
+                }
+            } else {
+                for (let i = 0; i < ctx.palette_size_uv; i++) {
+                    ctx.palette_colors_v[i] = reader.read_literal(bit_depth);
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Merge the palettes of the blocks above and to the left into `ctx.palette_cache`.
+ *
+ * Both are already in ascending order, so this is a merge rather than a sort, and duplicates are
+ * dropped as they appear.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {number} plane `0` luma, `1` chroma
+ * @returns {number} the number of cached colours
+ * @see AV1 spec 5.11.46, `get_palette_cache`
+ */
+function build_palette_cache(ctx, plane) {
+    const mi_count = ctx.mi_stride * ctx.mi_rows;
+    const size_base = plane * mi_count;
+    const colour_base = plane * mi_count * MAX_PALETTE_SIZE;
+
+    // the above palette is only visible within the same 64-sample row of superblocks
+    const above_available = (ctx.mi_row * MI_SIZE) % 64 !== 0;
+
+    const above_index = (ctx.mi_row - 1) * ctx.mi_stride + ctx.mi_col;
+    const left_index = ctx.mi_row * ctx.mi_stride + ctx.mi_col - 1;
+
+    const above_count = above_available ? ctx.palette_sizes[size_base + above_index] : 0;
+    const left_count = ctx.avail_l === 1 ? ctx.palette_sizes[size_base + left_index] : 0;
+
+    const cache = ctx.palette_cache;
+    const colours = ctx.palette_colors;
+
+    let above_idx = 0;
+    let left_idx = 0;
+    let n = 0;
+
+    while (above_idx < above_count && left_idx < left_count) {
+        const above_colour = colours[colour_base + above_index * MAX_PALETTE_SIZE + above_idx];
+        const left_colour = colours[colour_base + left_index * MAX_PALETTE_SIZE + left_idx];
+
+        if (left_colour < above_colour) {
+            if (n === 0 || left_colour !== cache[n - 1]) {
+                cache[n++] = left_colour;
+            }
+
+            left_idx++;
+        } else {
+            if (n === 0 || above_colour !== cache[n - 1]) {
+                cache[n++] = above_colour;
+            }
+
+            above_idx++;
+
+            if (left_colour === above_colour) {
+                left_idx++;
+            }
+        }
+    }
+
+    while (above_idx < above_count) {
+        const value = colours[colour_base + above_index * MAX_PALETTE_SIZE + above_idx];
+
+        above_idx++;
+
+        if (n === 0 || value !== cache[n - 1]) {
+            cache[n++] = value;
+        }
+    }
+
+    while (left_idx < left_count) {
+        const value = colours[colour_base + left_index * MAX_PALETTE_SIZE + left_idx];
+
+        left_idx++;
+
+        if (n === 0 || value !== cache[n - 1]) {
+            cache[n++] = value;
+        }
+    }
+
+    return n;
+}
+
+/**
+ * @param {Uint16Array} palette
+ * @param {number} count
+ */
+function sort_palette(palette, count) {
+    // insertion sort: the array is at most eight entries and usually already ordered
+    for (let i = 1; i < count; i++) {
+        const value = palette[i];
+
+        let j = i - 1;
+
+        while (j >= 0 && palette[j] > value) {
+            palette[j + 1] = palette[j];
+            j--;
+        }
+
+        palette[j + 1] = value;
+    }
+}
+
+/**
+ * Read the colour index maps for a palette block.
+ *
+ * The map is coded along anti-diagonals so that every sample has its left, above and above-left
+ * neighbours already decoded. Samples beyond the visible edge of the frame are not coded at all;
+ * they are filled by extending the last coded column and row, which keeps prediction well defined
+ * without spending bits on samples nobody sees.
+ *
+ * @param {Av1FrameContext} ctx
+ * @see AV1 spec 5.11.49 "Palette tokens syntax"
+ */
+export function read_palette_tokens(ctx) {
+    const reader = ctx.reader;
+
+    let block_height = BLOCK_HEIGHT[ctx.mi_size];
+    let block_width = BLOCK_WIDTH[ctx.mi_size];
+
+    let onscreen_height = Math.min(block_height, (ctx.mi_rows - ctx.mi_row) * MI_SIZE);
+    let onscreen_width = Math.min(block_width, (ctx.mi_cols - ctx.mi_col) * MI_SIZE);
+
+    const stride = ctx.color_map_stride;
+
+    if (ctx.palette_size_y > 0) {
+        const map = ctx.color_map_y;
+
+        map[0] = reader.read_ns(ctx.palette_size_y);
+
+        read_colour_map(ctx, map, stride, onscreen_width, onscreen_height, ctx.palette_size_y, ctx.cdf.palette_y_color);
+
+        extend_colour_map(map, stride, block_width, block_height, onscreen_width, onscreen_height);
+    }
+
+    if (ctx.palette_size_uv > 0) {
+        const map = ctx.color_map_uv;
+
+        map[0] = reader.read_ns(ctx.palette_size_uv);
+
+        block_height = block_height >> ctx.subsampling_y;
+        block_width = block_width >> ctx.subsampling_x;
+        onscreen_height = onscreen_height >> ctx.subsampling_y;
+        onscreen_width = onscreen_width >> ctx.subsampling_x;
+
+        // a 4x4 luma block subsamples to 2x2 chroma, which is smaller than the smallest transform;
+        // the map is grown to 4 so the prediction has something to read
+        if (block_width < 4) {
+            block_width += 2;
+            onscreen_width += 2;
+        }
+
+        if (block_height < 4) {
+            block_height += 2;
+            onscreen_height += 2;
+        }
+
+        read_colour_map(ctx, map, stride, onscreen_width, onscreen_height, ctx.palette_size_uv, ctx.cdf.palette_uv_color);
+
+        extend_colour_map(map, stride, block_width, block_height, onscreen_width, onscreen_height);
+    }
+}
+
+/**
+ * @param {Av1FrameContext} ctx
+ * @param {Uint8Array} map
+ * @param {number} stride
+ * @param {number} width
+ * @param {number} height
+ * @param {number} palette_size
+ * @param {Uint16Array[]} colour_cdfs
+ */
+function read_colour_map(ctx, map, stride, width, height, palette_size, colour_cdfs) {
+    const reader = ctx.reader;
+
+    const cdf = colour_cdfs[palette_size - 2];
+    const stride_symbols = palette_size + 1;
+
+    for (let i = 1; i < height + width - 1; i++) {
+        for (let j = Math.min(i, width - 1); j >= Math.max(0, i - height + 1); j--) {
+            const r = i - j;
+
+            const hash = compute_colour_context(ctx, map, stride, r, j, palette_size);
+            const context = PALETTE_COLOR_CONTEXT[hash];
+
+            const symbol = reader.read_symbol(cdf, context * stride_symbols, palette_size);
+
+            map[r * stride + j] = ctx.color_order[symbol];
+        }
+    }
+}
+
+/**
+ * @param {Uint8Array} map
+ * @param {number} stride
+ * @param {number} block_width
+ * @param {number} block_height
+ * @param {number} onscreen_width
+ * @param {number} onscreen_height
+ */
+function extend_colour_map(map, stride, block_width, block_height, onscreen_width, onscreen_height) {
+    for (let i = 0; i < onscreen_height; i++) {
+        for (let j = onscreen_width; j < block_width; j++) {
+            map[i * stride + j] = map[i * stride + onscreen_width - 1];
+        }
+    }
+
+    for (let i = onscreen_height; i < block_height; i++) {
+        for (let j = 0; j < block_width; j++) {
+            map[i * stride + j] = map[(onscreen_height - 1) * stride + j];
+        }
+    }
+}
+
+/**
+ * Rank the palette colours by how strongly the decoded neighbours vote for them, and return the
+ * hash that selects the context.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {Uint8Array} map
+ * @param {number} stride
+ * @param {number} r
+ * @param {number} c
+ * @param {number} n palette size
+ * @returns {number} the colour context hash
+ * @see AV1 spec 5.11.50 "Palette color context function"
+ */
+function compute_colour_context(ctx, map, stride, r, c, n) {
+    const scores = ctx.color_scores;
+    const order = ctx.color_order;
+
+    for (let i = 0; i < PALETTE_COLORS; i++) {
+        scores[i] = 0;
+        order[i] = i;
+    }
+
+    if (c > 0) {
+        scores[map[r * stride + c - 1]] += 2;
+    }
+
+    if (r > 0 && c > 0) {
+        scores[map[(r - 1) * stride + c - 1]] += 1;
+    }
+
+    if (r > 0) {
+        scores[map[(r - 1) * stride + c]] += 2;
+    }
+
+    for (let i = 0; i < PALETTE_NUM_NEIGHBORS; i++) {
+        let max_score = scores[i];
+        let max_idx = i;
+
+        for (let j = i + 1; j < n; j++) {
+            if (scores[j] > max_score) {
+                max_score = scores[j];
+                max_idx = j;
+            }
+        }
+
+        if (max_idx !== i) {
+            const max_order = order[max_idx];
+
+            for (let k = max_idx; k > i; k--) {
+                scores[k] = scores[k - 1];
+                order[k] = order[k - 1];
+            }
+
+            scores[i] = max_score;
+            order[i] = max_order;
+        }
+    }
+
+    let hash = 0;
+
+    for (let i = 0; i < PALETTE_NUM_NEIGHBORS; i++) {
+        hash += scores[i] * PALETTE_COLOR_HASH_MULTIPLIERS[i];
+    }
+
+    return hash;
+}

package/src/avif/native/av1/decode/decode_tile.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Decode one tile's worth of superblocks.
+ *
+ * The symbol reader must already be initialised over the tile's payload, and the tile bounds must
+ * be set on the context.
+ *
+ * @param {Av1FrameContext} ctx
+ * @see AV1 spec 5.11.2 "Decode tile syntax"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function decode_tile(ctx: Av1FrameContext): void;
+//# sourceMappingURL=decode_tile.d.ts.map

package/src/avif/native/av1/decode/decode_tile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode_tile.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/decode/decode_tile.js"],"names":[],"mappings":"AA8DA;;;;;;;;;;;GAWG;AACH,wDAmCC"}