imagediff

Compare two RGBA8 buffers and reduce them to scalar difference metrics.

local imagediff = require("@builtin::modules.imagediff")

local result = imagediff.compare(actualRgba, expectedRgba, 128, 128, { pixelThreshold = 4 })
if result.diffPixelRatio > 0.01 then
    -- images differ beyond tolerance
end

compare takes two raw RGBA8 strings (4 bytes per pixel, row-major) plus their shared dimensions, and returns maxDelta, meanDelta, diffPixelRatio, diffPixelCount and pixelCount. It raises when a buffer length does not match the given dimensions.

Options:

• pixelThreshold — per-channel delta at or below which a pixel counts as unchanged. Defaults to 0.
• compareAlpha — whether alpha participates. Defaults to true.