Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.0

0.6.0 / src / web / platform / image_codec_plugin_luce_decode.lucb

#==============================================================================================
#
#   image_codec_plugin_luce_decode - the engine's image decoders: PNG (and APNG), JPEG, GIF,
#   WebP, BMP and ICO/CUR through our luce packages, converted to premultiplied BGRA8888 bitmaps
#
#   DESCRIPTION:
#       What Ladybird's ImageDecoder process does with LibGfx (Services/ImageDecoder/
#       ConnectionFromClient.cpp decode_image_to_details, LibGfx/ImageFormats/ImageDecoder.cpp
#       probe_and_sniff_for_appropriate_plugin), done in process over our own decoders
#       (DESIGN.md ยง7.0): luce-png, luce-jpeg, luce-gif, luce-webp, luce-bmp and luce-ico (WebP
#       and APNG in platform/image_codec_plugin_luce_animation). Not a port: new code behind
#       the ported seam, platform/image_codec_plugin_luce.
#
#       The decoder is chosen by the bytes, as LibGfx sniffs them: MimeSniff's "match an
#       image type pattern" (ported, r13) names the type, and the type's essence names the
#       decoder, so image/png, image/jpeg, image/gif, image/webp, image/bmp and image/x-icon
#       (icons and cursors) and the declared image/vnd.microsoft.icon reach theirs. AVIF (an
#       ISO BMFF file of brand avif or avis) fails as not supported yet, as does anything
#       else. An animated PNG decodes as Ladybird's PNG loader composites it. The packages
#       give 8-bit straight RGBA; this fragment converts it to the
#       bitmaps gfx and the rasterizer draw, premultiplied BGRA8888 (raster.premultiply_u8,
#       Skia's rounding), as LibGfx's frames are made premultiplied with
#       set_alpha_type_destructive.
#
#       A decoded image carries its color space, as ImageDecoder::color_space gives it to
#       decode_image_to_details (LibGfx/ImageFormats/ImageDecoder.cpp): a PNG's cICP chunk
#       (PNGLoader reads it in preference to iCCP) through ColorSpace::from_cicp, refused for
#       matrix coefficients other than identity or studio range; else the ICC profile, a PNG's
#       iCCP (luce-png reads it as libpng does), a JPEG's APP2 segments (luce-jpeg joins them
#       as libjpeg-turbo does) or a WebP's ICCP chunk (luce-webp reads it as WebPMux does),
#       through ColorSpace::load_from_icc_bytes; else sRGB. A color space that fails is sRGB,
#       as decode_image_to_details only logs the error. A BMP with a BITMAPV5HEADER gives its
#       embedded profile (BMPImageDecoderPlugin::icc_data); the other formats are sRGB, as in
#       Ladybird's GIF and ICO plugins.
#
#       A GIF's frames are whole canvases, each composited over what the frames before it
#       left (luce-gif's Animation, as browsers draw them), with the durations browsers play
#       (a delay of 10 ms or less plays as 100 ms, as LibGfx's GIFLoader does too) and the
#       number of plays browsers make as the loop count (0 forever, 1 without a loop
#       extension, else the count written and the first play), which is what
#       HTMLImageElement and ImageStyleValue count completed loops against.
#
#       Copyright (c) 2026 the luce-browser authors.
#       SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================

# mark: Choosing the decoder ====================================================================

## The image could not be decoded.
pub let luce_image_codec_unsupported: ErrorCode = ErrorCode.package(5)

## The formats the plugin tells apart.
enum LuceImageCodecFormat:
    png
    jpeg
    gif
    bmp
    ico
    webp
    avif
    unknown

## The decoder for an image MIME type's essence (ASCII case-insensitive): image/x-icon and
## image/vnd.microsoft.icon are both icons (and cursors).
func luce_image_codec_format_for_essence(essence: ak.StringView) -> LuceImageCodecFormat:
    if ak.string_view_equals_ignoring_ascii_case(&essence, ak.sv("image/png")):
        return LuceImageCodecFormat.png
    if ak.string_view_equals_ignoring_ascii_case(&essence, ak.sv("image/jpeg")):
        return LuceImageCodecFormat.jpeg
    if ak.string_view_equals_ignoring_ascii_case(&essence, ak.sv("image/gif")):
        return LuceImageCodecFormat.gif
    if ak.string_view_equals_ignoring_ascii_case(&essence, ak.sv("image/bmp")):
        return LuceImageCodecFormat.bmp
    if ak.string_view_equals_ignoring_ascii_case(&essence, ak.sv("image/x-icon")) or ak.string_view_equals_ignoring_ascii_case(&essence, ak.sv("image/vnd.microsoft.icon")):
        return LuceImageCodecFormat.ico
    if ak.string_view_equals_ignoring_ascii_case(&essence, ak.sv("image/webp")):
        return LuceImageCodecFormat.webp
    if ak.string_view_equals_ignoring_ascii_case(&essence, ak.sv("image/avif")):
        return LuceImageCodecFormat.avif
    return LuceImageCodecFormat.unknown

## Whether `bytes` start an ISO BMFF file whose major brand is AVIF's (`ftyp` then `avif` or `avis`).
func luce_image_codec_is_avif(bytes: const u8[]) -> bool:
    if bytes.length < 12 or bytes[4] != 'f' or bytes[5] != 't' or bytes[6] != 'y' or bytes[7] != 'p':
        return false
    return bytes[8] == 'a' and bytes[9] == 'v' and bytes[10] == 'i' and (bytes[11] == 'f' or bytes[11] == 's')

## The format of the image in `bytes`, by MimeSniff's image type pattern (and AVIF's file type box).
func luce_image_codec_sniff(bytes: const u8[]) -> LuceImageCodecFormat:
    if let mime_type = match_an_image_type_pattern(bytes):
        let essence = mime_type_essence(&mime_type)
        return luce_image_codec_format_for_essence(ak.string_bytes_as_string_view(&essence))
    if luce_image_codec_is_avif(bytes):
        return LuceImageCodecFormat.avif
    return LuceImageCodecFormat.unknown

# mark: Decoding ================================================================================

## The decoded image of a PNG, JPEG, GIF, WebP, BMP or ICO/CUR file, every frame a premultiplied
## BGRA8888 bitmap: one for a still image, every composited frame of an animated GIF, WebP or PNG
## (with its durations and loop count). The plugin's decode_image streams an animation's frames
## instead.
pub func luce_image_codec_plugin_decode(bytes: const u8[]) -> PlatformDecodedImage!:
    match luce_image_codec_sniff(bytes):
        .png:
            if luce_image_codec_is_apng(bytes):
                return try luce_image_codec_decode_apng(bytes)
            var image = luce_image_codec_still(try luce_image_codec_decode_png(bytes), 0, 0)
            image.color_space = luce_image_codec_png_color_space(bytes)
            return image
        .jpeg:
            var image = luce_image_codec_still(try luce_image_codec_decode_jpeg(bytes), 0, 0)
            image.color_space = luce_image_codec_jpeg_color_space(bytes)
            return image
        .gif:
            return try luce_image_codec_decode_gif(bytes)
        .bmp:
            var image = luce_image_codec_still(try luce_image_codec_decode_bmp(bytes), 0, 0)
            image.color_space = luce_image_codec_bmp_color_space(bytes)
            return image
        .ico:
            return luce_image_codec_still(try luce_image_codec_decode_ico(bytes), 0, 0)
        .webp:
            return try luce_image_codec_decode_webp(bytes)
        .avif:
            error(luce_image_codec_unsupported, "AVIF images are not supported yet")
        .unknown:
            error(luce_image_codec_unsupported, "Unsupported image format")

## A decoded image of one frame shown for `duration` ms and played `loop_count` times.
func luce_image_codec_still(bitmap: gfx.Bitmap*, duration: u32, loop_count: u32) -> PlatformDecodedImage:
    var image = PlatformDecodedImage(color_space = luce_image_codec_srgb())
    image.loop_count = loop_count
    image.frame_count = 1
    ak.vector_append_t(&image.frames, PlatformFrame(bitmap = bitmap, duration = (usize)duration))
    ak.vector_append_t(&image.all_durations, duration)
    return image

## The default color space: none, which is sRGB.
func luce_image_codec_srgb() -> gfx.ColorSpace:
    var color_space: gfx.ColorSpace = ---
    gfx.color_space_construct(&color_space)
    return color_space

# mark: Color spaces ============================================================================

## ImageDecoder::color_space for a cICP chunk's code points: ColorSpace::from_cicp, refused
## (sRGB) for matrix coefficients other than identity or a studio range.
func luce_image_codec_cicp_color_space(cicp: png_codec.Cicp) -> gfx.ColorSpace:
    # "Unsupported matrix coefficients for CICP", "Studio range is not supported".
    if cicp.matrix_coefficients != (u8)gfx.MediaMatrixCoefficients.identity or cicp.video_full_range != (u8)gfx.MediaVideoFullRangeFlag.full:
        return luce_image_codec_srgb()
    let code_points = gfx.MediaCodingIndependentCodePoints(m_color_primaries = (gfx.MediaColorPrimaries)cicp.color_primaries, m_transfer_characteristics = (gfx.MediaTransferCharacteristics)cicp.transfer_function,
                                                           m_matrix_coefficients = (gfx.MediaMatrixCoefficients)cicp.matrix_coefficients, m_video_full_range_flag = (gfx.MediaVideoFullRangeFlag)cicp.video_full_range)
    return gfx.color_space_from_cicp(code_points) else luce_image_codec_srgb()

## ImageDecoder::color_space for an ICC profile: ColorSpace::load_from_icc_bytes, sRGB when it
## fails.
func luce_image_codec_icc_color_space(profile: const u8[]) -> gfx.ColorSpace:
    return gfx.color_space_load_from_icc_bytes(profile) else luce_image_codec_srgb()

## A PNG's color space: its cICP chunk, else its iCCP profile, else sRGB.
func luce_image_codec_png_color_space(bytes: const u8[]) -> gfx.ColorSpace:
    let found = png_codec.info(bytes) else return luce_image_codec_srgb()
    if let cicp = found.colorimetry.cicp:
        return luce_image_codec_cicp_color_space(cicp)
    var profile: u8[]? = none
    with memory.heap:
        profile = png_codec.icc_profile(&found) else none
    let bytes_of_profile = profile else return luce_image_codec_srgb()
    defer free(bytes_of_profile) in memory.heap
    return luce_image_codec_icc_color_space(bytes_of_profile)

## A JPEG's color space: its ICC profile, else sRGB.
func luce_image_codec_jpeg_color_space(bytes: const u8[]) -> gfx.ColorSpace:
    var profile: u8[]? = none
    with memory.heap:
        profile = jpeg_codec.icc_profile(bytes) else none
    let bytes_of_profile = profile else return luce_image_codec_srgb()
    defer free(bytes_of_profile) in memory.heap
    return luce_image_codec_icc_color_space(bytes_of_profile)

## A PNG's image (its default image, for an animated PNG).
func luce_image_codec_decode_png(bytes: const u8[]) -> gfx.Bitmap*!:
    let found = try png_codec.info(bytes)
    try luce_image_codec_check_size(found.width, found.height)
    let pixels = try new u8[found.width * found.height * 4] --- in memory.heap
    defer free(pixels) in memory.heap
    with memory.heap:
        try png_codec.decode_rgba8(bytes, pixels)
    return try luce_image_codec_bitmap(pixels, found.width, found.height)

## Whether `bytes` are an animated PNG: an acTL chunk before the image data.
func luce_image_codec_is_apng(bytes: const u8[]) -> bool:
    let found = png_codec.info(bytes) else return false
    return found.animated

## A JPEG's image.
func luce_image_codec_decode_jpeg(bytes: const u8[]) -> gfx.Bitmap*!:
    let found = try jpeg_codec.info(bytes)
    try luce_image_codec_check_size(found.width, found.height)
    let pixels = try new u8[found.width * found.height * 4] --- in memory.heap
    defer free(pixels) in memory.heap
    with memory.heap:
        try jpeg_codec.decode_rgba8(bytes, pixels)
    return try luce_image_codec_bitmap(pixels, found.width, found.height)

## ImageDecoder::color_space for a BMP (BMPImageDecoderPlugin::icc_data): the ICC profile of a
## BITMAPV5HEADER (a DIB header of 124 bytes) whose color space type is PROFILE_EMBEDDED
## ('MBED') and that has profile data, which starts profile_data bytes after the 14-byte file
## header; else sRGB, as Ladybird leaves LINKED, sRGB, WINDOWS_COLOR_SPACE, CALIBRATED_RGB and
## the older headers (FIXMEs there). A profile that runs past the file is an error, which
## decode_image_to_details logs: sRGB too. An icon's BMP entries have no color space
## (ICOImageDecoderPlugin has no icc_data).
func luce_image_codec_bmp_color_space(bytes: const u8[]) -> gfx.ColorSpace:
    let file_header: usize = 14
    if bytes.length < file_header + 124:
        return luce_image_codec_srgb()
    if luce_image_codec_bmp_le32(bytes, file_header) != 124 or luce_image_codec_bmp_le32(bytes, file_header + 56) != 0x4D424544:
        return luce_image_codec_srgb()
    let profile_data = (usize)luce_image_codec_bmp_le32(bytes, file_header + 112)
    let profile_size = (usize)luce_image_codec_bmp_le32(bytes, file_header + 116)
    if profile_data == 0 or profile_size == 0 or profile_data + file_header + profile_size > bytes.length:
        return luce_image_codec_srgb()
    return luce_image_codec_icc_color_space(bytes[file_header + profile_data..<file_header + profile_data + profile_size])

## The little-endian u32 at `offset`.
func luce_image_codec_bmp_le32(bytes: const u8[], offset: usize) -> u32:
    return (u32)bytes[offset] | ((u32)bytes[offset + 1] << 8) | ((u32)bytes[offset + 2] << 16) | ((u32)bytes[offset + 3] << 24)

## A BMP's image; one holding a PNG or JPEG (BI_PNG, BI_JPEG) is that image.
func luce_image_codec_decode_bmp(bytes: const u8[]) -> gfx.Bitmap*!:
    if let payload = bmp_codec.embedded(bytes):
        match luce_image_codec_sniff(payload):
            .png:
                return try luce_image_codec_decode_png(payload)
            .jpeg:
                return try luce_image_codec_decode_jpeg(payload)
            _:
                error(luce_image_codec_unsupported, "the BMP holds neither a PNG nor a JPEG")
    let found = try bmp_codec.info(bytes)
    try luce_image_codec_check_size(found.width, found.height)
    let pixels = try new u8[found.width * found.height * 4] --- in memory.heap
    defer free(pixels) in memory.heap
    with memory.heap:
        try bmp_codec.decode_rgba8(bytes, pixels)
    return try luce_image_codec_bitmap(pixels, found.width, found.height)

## An icon's or cursor's image: the entry luce-ico chooses (the largest, then the one with the most
## bits, then the first), a BMP entry with its AND mask, a PNG entry decoded as a PNG. An entry whose
## image is not the size its directory lists does not decode (as Ladybird and Firefox require).
func luce_image_codec_decode_ico(bytes: const u8[]) -> gfx.Bitmap*!:
    let entry = try ico_codec.choose(bytes)
    if not entry.readable:
        error(ico_codec.corrupt, "the icon's image is damaged or not the size its directory lists")
    if entry.png:
        return try luce_image_codec_decode_png(ico_codec.image(bytes, &entry))
    try luce_image_codec_check_size(entry.width, entry.height)
    let pixels = try new u8[entry.width * entry.height * 4] --- in memory.heap
    defer free(pixels) in memory.heap
    with memory.heap:
        try ico_codec.decode_rgba8(bytes, &entry, pixels)
    return try luce_image_codec_bitmap(pixels, entry.width, entry.height)

## Every frame of a GIF, composited (decode_image_to_bitmaps_and_durations_with_decoder): one frame
## for a still GIF, all of an animation's with their durations.
func luce_image_codec_decode_gif(bytes: const u8[]) -> PlatformDecodedImage!:
    var animation = try luce_image_codec_gif_open(bytes)
    defer animation.release()
    let frames = animation.frames()
    var image = PlatformDecodedImage(color_space = luce_image_codec_srgb())
    image.is_animated = animation.info.animated()
    image.loop_count = animation.info.plays()
    image.frame_count = (u32)frames.length
    let pixels = try new u8[animation.info.width * animation.info.height * 4] --- in memory.heap
    defer free(pixels) in memory.heap
    for index in 0..<frames.length:
        let bitmap = try luce_image_codec_gif_frame(&animation, index, pixels)
        ak.vector_append_t(&image.frames, PlatformFrame(bitmap = bitmap, duration = (usize)frames[index].duration))
        ak.vector_append_t(&image.all_durations, frames[index].duration)
    return image

## A GIF's animation over `bytes` (which must outlive it), its canvas checked.
func luce_image_codec_gif_open(bytes: const u8[]) -> gif_codec.Animation!:
    var animation = try gif_codec.Animation.open(bytes)
    errdefer animation.release()
    try luce_image_codec_check_size(animation.info.width, animation.info.height)
    return animation

## Frame `index` of a GIF animation, composited, rendered through `pixels` (a canvas of RGBA).
func luce_image_codec_gif_frame(animation: gif_codec.Animation*, index: usize, pixels: u8[]) -> gfx.Bitmap*!:
    try animation.render(index, pixels)
    return try luce_image_codec_bitmap(pixels, animation.info.width, animation.info.height)

# mark: Bitmaps =================================================================================

## Fails for a picture with no pixels or too many (above 2^14 on a side, as Gfx::Bitmap's size check).
func luce_image_codec_check_size(width: usize, height: usize) -> !:
    if width == 0 or height == 0 or width > 16384 or height > 16384:
        error(luce_image_codec_unsupported, "the image's size is out of range")

## A premultiplied BGRA8888 bitmap of the 8-bit RGBA `pixels`.
func luce_image_codec_bitmap(pixels: const u8[], width: usize, height: usize) -> gfx.Bitmap*!:
    let size = gfx.IntSize(m_width = (i32)width, m_height = (i32)height)
    let bitmap = try gfx.bitmap_create_alpha_type(gfx.BitmapFormat.bgra8888, gfx.AlphaType.premultiplied, size)
    for y in 0..<height:
        let row = gfx.bitmap_scanline(bitmap, (i32)y) else trap("VERIFY: bitmap data")
        let source = pixels[y * width * 4..]
        for x in 0..<width:
            let alpha = source[x * 4 + 3]
            let red = (u32)raster.premultiply_u8(source[x * 4], alpha)
            let green = (u32)raster.premultiply_u8(source[x * 4 + 1], alpha)
            let blue = (u32)raster.premultiply_u8(source[x * 4 + 2], alpha)
            row[x] = ((u32)alpha << 24) | (red << 16) | (green << 8) | blue
    return bitmap