Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-engine

Source of release 0.6.0

0.6.0 / src / web / platform / image_codec_plugin_luce.lucb

#==============================================================================================
#
#   image_codec_plugin_luce - the engine's Platform::ImageCodecPlugin: images decoded in
#   process by our luce packages, animations (GIF, WebP, APNG) streamed frame by frame
#
#   DESCRIPTION:
#       Ladybird's WebView::ImageCodecPlugin (Libraries/LibWebView/Plugins/ImageCodecPlugin.cpp)
#       sends the bytes to its ImageDecoder process (Services/ImageDecoder/
#       ConnectionFromClient.cpp), which decodes with LibGfx. Here the plugin decodes in process
#       with our own decoders (DESIGN.md §7.0; the formats and the conversion to premultiplied
#       BGRA8888 are in image_codec_plugin_luce_decode). Not a port: new code behind the ported
#       seam, shaped as the ImageDecoder answers.
#
#       decode_image answers a promise at once and decodes on the next turn of the event loop,
#       as the ImageDecoder's reply arrives later. A still image resolves with its one frame.
#       An animated GIF, WebP or PNG of more than one frame starts a streaming session, as
#       ConnectionFromClient does for an animated image: the promise hears every frame's
#       duration, the loop count, the session id and the first STREAMING_BATCH_SIZE composited
#       frames, and the plugin keeps the image (a copy of its bytes, in the C heap) for
#       request_animation_frames, which decodes the frames AnimatedDecodedImageData asks for
#       on a later turn and hands them to on_animation_frames_decoded (or reports
#       on_animation_decode_failed). stop_animation_decode ends the session and cancels a
#       request not yet decoded.
#
#       Copyright (c) 2026 the luce-browser authors.
#       SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================

# mark: The plugin ==============================================================================

## The image codec plugin over our luce decoders, in the C heap for the process (DESIGN.md §3.3 rule 7).
pub struct LuceImageCodecPlugin: IsPlatformImageCodecPlugin:
    pub var plugin: PlatformImageCodecPlugin  # the seam's plugin first: a pointer to one is a pointer to the other
    ## The streaming sessions of animated images (ConnectionFromClient::m_animation_sessions), in the C heap.
    var m_animation_sessions: ak.HashMap[i64, LuceImageCodecAnimationSession*, ak.I64Traits]
    var m_next_session_id: i64 = 1

    func platform_image_codec_plugin() -> PlatformImageCodecPlugin*: return (PlatformImageCodecPlugin*)&self

## An animated image whose frames the plugin decodes on request (ConnectionFromClient::AnimationSession),
## all in the C heap.
struct LuceImageCodecAnimationSession:
    ## A copy of the image, which the animation reads.
    var encoded_data: u8[]
    var animation: LuceImageCodecAnimation
    ## The canvas each frame is rendered through, RGBA.
    var pixels: u8[]
    var frame_count: u32

## ConnectionFromClient's STREAMING_BATCH_SIZE: how many frames of an animation the first answer holds.
let luce_image_codec_streaming_batch_size: u32 = 4

## The plugin's vtable.
let luce_image_codec_plugin_vtable: PlatformImageCodecPluginVTable = PlatformImageCodecPluginVTable(class_info = &platform_image_codec_plugin_class,
                                                                                                    decode_image = luce_image_codec_plugin_decode_image,
                                                                                                    request_animation_frames = luce_image_codec_plugin_request_animation_frames,
                                                                                                    stop_animation_decode = luce_image_codec_plugin_stop_animation_decode)

## Makes the plugin in the C heap for the process and installs it (WebContent's main: ImageCodecPlugin::install).
pub func luce_image_codec_plugin_install():
    with memory.heap:
        let plugin = new LuceImageCodecPlugin(plugin = PlatformImageCodecPlugin(vtable = &luce_image_codec_plugin_vtable)) else trap("out of memory")
        platform_image_codec_plugin_install(plugin.platform_image_codec_plugin())

# mark: Decoding an image =======================================================================

## The captures of decode_image's deferred decode: the plugin, the bytes (copied, as the IPC message
## copies them) and the promise.
struct LuceImageCodecPluginDecode:
    var plugin: LuceImageCodecPlugin*
    var bytes: ak.ByteBuffer
    var promise: CorePromise[PlatformDecodedImage, ak.AkError]*

    ## The deferred decode (the decode job and its completion): resolves the promise with the
    ## decoded image, or rejects it.
    static func call(context: void*?):
        let captures = (LuceImageCodecPluginDecode*)(context else trap("decode_image: no captures"))
        let image = luce_image_codec_plugin_decode_details(captures.plugin, ak.byte_buffer_bytes_const(&captures.bytes)) catch failure:
            core_promise_reject(captures.promise, ak.ak_error_from_failure(failure))
            return
        core_promise_resolve(captures.promise, image)

## ImageCodecPlugin::decode_image: a promise whose handlers are `on_resolved` and `on_rejected`, settled on the
## next turn of the event loop.
func luce_image_codec_plugin_decode_image(this: PlatformImageCodecPlugin*, bytes: const u8[], on_resolved: ak.Function1[PlatformDecodedImage*, unit],
                                          on_rejected: ak.Function1[ak.AkError*, unit]) -> CorePromise[PlatformDecodedImage, ak.AkError]*:
    let promise = core_promise_construct[PlatformDecodedImage, ak.AkError]()
    if ak.function1_is_set(&on_resolved):
        promise.on_resolution = on_resolved
    if ak.function1_is_set(&on_rejected):
        promise.on_rejection = on_rejected

    let copy = ak.byte_buffer_copy_span_u8(bytes) else trap("out of memory")
    let captures = new LuceImageCodecPluginDecode(plugin = (LuceImageCodecPlugin*)this, bytes = copy, promise = promise) else trap("out of memory")
    core_deferred_invoke(ak.Function0[unit](call = LuceImageCodecPluginDecode.call, context = captures))
    return promise

## decode_image_to_details with the job's completion: an animated GIF, WebP or PNG of more than one
## frame starts a streaming session and answers its first frames; anything else decodes whole.
func luce_image_codec_plugin_decode_details(this: LuceImageCodecPlugin*, bytes: const u8[]) -> PlatformDecodedImage!:
    let kind = luce_image_codec_sniff(bytes)
    if try luce_image_codec_plugin_streams(kind, bytes):
        return try luce_image_codec_plugin_start_session(this, kind, bytes)
    return try luce_image_codec_plugin_decode(bytes)

## Whether the image in `bytes`, of `kind`, is an animation of more than one frame: one the plugin
## streams.
func luce_image_codec_plugin_streams(kind: LuceImageCodecFormat, bytes: const u8[]) -> bool!:
    match kind:
        .gif:
            let found = try gif_codec.info(bytes)
            return found.animated()
        .webp:
            return try luce_image_codec_webp_streams(bytes)
        .png:
            return luce_image_codec_apng_streams(bytes)
        _:
            return false

# mark: Streaming animations ====================================================================

## Opens a streaming session on the animated image in `bytes`, of `kind`: every frame's duration (no
## pixels decoded for them), the loop count, the color space, and the first STREAMING_BATCH_SIZE frames
## composited; the session keeps a copy of the image for the frames requested later.
func luce_image_codec_plugin_start_session(this: LuceImageCodecPlugin*, kind: LuceImageCodecFormat, bytes: const u8[]) -> PlatformDecodedImage!:
    let session = try luce_image_codec_animation_session_create(kind, bytes)
    errdefer luce_image_codec_animation_session_destroy(session)

    var image = PlatformDecodedImage(color_space = try luce_image_codec_animation_color_space(kind, bytes))
    image.is_animated = true
    image.loop_count = session.animation.loop_count
    image.frame_count = session.frame_count
    # Collect all durations cheaply (no pixel decode).
    for index in 0..<(usize)session.frame_count:
        ak.vector_append_t(&image.all_durations, session.animation.duration(index))

    # Decode only the first batch of frames.
    let batch_size = ak.min(luce_image_codec_streaming_batch_size, session.frame_count)
    for index in 0..<(usize)batch_size:
        let bitmap = try luce_image_codec_animation_frame(&session.animation, index, session.pixels)
        ak.vector_append_t(&image.frames, PlatformFrame(bitmap = bitmap, duration = (usize)session.animation.duration(index)))

    # Keep the decoder for future frame requests.
    image.session_id = this.m_next_session_id
    this.m_next_session_id += 1
    with memory.heap:
        _ = ak.hash_map_set(&this.m_animation_sessions, image.session_id, session)
    return image

## The color space of an animated image of `kind`: a WebP's ICC profile (a file whose chunks WebPMux
## refuses fails), a PNG's cICP or iCCP, else sRGB.
func luce_image_codec_animation_color_space(kind: LuceImageCodecFormat, bytes: const u8[]) -> gfx.ColorSpace!:
    match kind:
        .webp:
            return luce_image_codec_webp_color_space(try webp_codec.icc_profile(bytes))
        .png:
            return luce_image_codec_png_color_space(bytes)
        _:
            return luce_image_codec_srgb()

## A session over a C-heap copy of the animated image in `bytes`, of `kind`.
func luce_image_codec_animation_session_create(kind: LuceImageCodecFormat, bytes: const u8[]) -> LuceImageCodecAnimationSession*!:
    let encoded_data = try new u8[bytes.length] --- in memory.heap
    errdefer free(encoded_data) in memory.heap
    memory.copy(encoded_data, bytes, bytes.length)
    var animation = try luce_image_codec_animation_open(kind, encoded_data)
    errdefer animation.release()
    let pixels = try new u8[animation.width * animation.height * 4] --- in memory.heap
    errdefer free(pixels) in memory.heap
    let session = try new LuceImageCodecAnimationSession(encoded_data = encoded_data, animation = animation, pixels = pixels, frame_count = (u32)animation.frame_count) in memory.heap
    return session

## Frees a session and what it holds.
func luce_image_codec_animation_session_destroy(session: LuceImageCodecAnimationSession*):
    session.animation.release()
    free(session.pixels) in memory.heap
    free(session.encoded_data) in memory.heap
    free(session) in memory.heap

## The session `session_id`, if it is open.
func luce_image_codec_plugin_session(this: LuceImageCodecPlugin*, session_id: i64) -> LuceImageCodecAnimationSession*?:
    let entry = ak.hash_map_get_k(&this.m_animation_sessions, session_id) else return none
    return *entry

## The captures of request_animation_frames' deferred decode (a FrameDecodeJob).
struct LuceImageCodecPluginFrameRequest:
    var plugin: LuceImageCodecPlugin*
    var session_id: i64
    var start_frame_index: u32
    var end_index: u32

    ## The deferred decode with its completion: frames [start_frame_index, end_index) of the session,
    ## handed to on_animation_frames_decoded, or on_animation_decode_failed told. Nothing happens
    ## when the session was stopped first (the job was cancelled).
    static func call(context: void*?):
        let captures = (LuceImageCodecPluginFrameRequest*)(context else trap("request_animation_frames: no captures"))
        let plugin = captures.plugin
        let session = luce_image_codec_plugin_session(plugin, captures.session_id) else return
        var bitmaps: ak.Vector[gfx.Bitmap*]
        ak.vector_ensure_capacity(&bitmaps, (usize)(captures.end_index - captures.start_frame_index))
        for index in (usize)captures.start_frame_index..<(usize)captures.end_index:
            let bitmap = luce_image_codec_animation_frame(&session.animation, index, session.pixels) catch:
                if ak.function1_is_set(&plugin.plugin.on_animation_decode_failed):
                    ak.function1_call(&plugin.plugin.on_animation_decode_failed, captures.session_id)
                return
            ak.vector_append_t(&bitmaps, bitmap)
        if ak.function2_is_set(&plugin.plugin.on_animation_frames_decoded):
            ak.function2_call(&plugin.plugin.on_animation_frames_decoded, captures.session_id, bitmaps)

## ImageCodecPlugin::request_animation_frames (ConnectionFromClient::request_animation_frames): decodes
## up to `count` frames of the session from `start_frame_index` on the next turn of the event loop. An
## unknown session or a start past the last frame is ignored.
func luce_image_codec_plugin_request_animation_frames(this: PlatformImageCodecPlugin*, session_id: i64, start_frame_index: u32, count: u32):
    let plugin = (LuceImageCodecPlugin*)this
    let session = luce_image_codec_plugin_session(plugin, session_id) else return
    let frame_count = session.frame_count

    if start_frame_index >= frame_count:
        return

    let end_index = ak.min(frame_count, start_frame_index + ak.min(count, frame_count - start_frame_index))

    let captures = new LuceImageCodecPluginFrameRequest(plugin = plugin, session_id = session_id, start_frame_index = start_frame_index, end_index = end_index) else trap("out of memory")
    core_deferred_invoke(ak.Function0[unit](call = LuceImageCodecPluginFrameRequest.call, context = captures))

## ImageCodecPlugin::stop_animation_decode (ConnectionFromClient::stop_animation_decode): ends the session,
## so a request not yet decoded does nothing.
func luce_image_codec_plugin_stop_animation_decode(this: PlatformImageCodecPlugin*, session_id: i64):
    let plugin = (LuceImageCodecPlugin*)this
    let session = luce_image_codec_plugin_session(plugin, session_id) else return
    with memory.heap:
        _ = ak.hash_map_remove_k(&plugin.m_animation_sessions, session_id)
    luce_image_codec_animation_session_destroy(session)