dymokomi/luce-browser-engine
Source of release 0.6.1
0.6.1 / 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 memory_tag = memory_tag_enter(MemoryTag.image)
defer memory_tag_leave(memory_tag)
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)