///|
/// This package provides types related to JPEG XL frames.
///
/// A JPEG XL image contains one or more frames. A frame represents single unit of image that can
/// be displayed or referenced by other frames.
///
/// A frame consists of a few components:
/// - Frame header (`FrameHeader`).
/// - Table of contents (TOC, `Toc`).
/// - Actual frame data, in the following order, potentially permuted as specified in the TOC:
/// - one `LfGlobal`,
/// - `num_lf_groups` `LfGroup`'s, in raster order,
/// - one `HfGlobal`, potentially empty for Modular frames, and
/// - `num_passes` times `num_groups` pass groups (`decode_pass_group`), in raster order.
///|
/// JPEG XL frame.
///
/// A frame represents a single unit of image that can be displayed or referenced by other frames.
pub struct Frame {
priv tracker : @grid.AllocTracker?
priv image_header : @image.ImageHeader
priv header : FrameHeader
priv toc : Toc
priv data : Array[GroupData]
priv all_group_offsets : AllGroupOffsets
priv mut reading_data_index : Int32
priv pass_shifts : @sorted_map.SortedMap[Int32, (Int32, Int32)]
}
///|
priv struct AllGroupOffsets {
mut lf_group : Int32
mut hf_global : Int32
mut pass_group : Int32
mut has_error : Int32
}
///|
/// Bytes of one TOC group. Data fed in one piece is referenced without copying;
/// data fed in several pieces is accumulated in a buffer.
priv struct GroupData {
toc_group : TocGroup
mut view : BytesView
mut buf : Buffer?
mut allocated : Bool
}
///|
fn GroupData::from_toc_group(value : TocGroup) -> GroupData {
{ toc_group: value, view: b""[:], buf: None, allocated: false, }
}
///|
fn GroupData::len(self : GroupData) -> Int32 {
self.view.length()
}
///|
fn GroupData::ensure_allocated(
self : GroupData,
tracker : @grid.AllocTracker?,
) -> Unit raise @bitstream.JxlError {
if tracker is Some(tracker) {
if self.allocated {
return
}
tracker.alloc(self.toc_group.size, 1)
self.allocated = true
}
}
///|
fn GroupData::append(self : GroupData, chunk : BytesView) -> Unit {
if chunk.length() == 0 {
return
}
if self.view.length() == 0 && self.buf is None {
self.view = chunk
return
}
let buf = match self.buf {
Some(buf) => buf
None => {
let buf = Buffer(capacity=self.toc_group.size)
buf.write_bytesview(self.view)
self.buf = Some(buf)
buf
}
}
buf.write_bytesview(chunk)
self.view = buf.to_bytes()[:]
}
///|
fn bitstream_of(view : BytesView) -> @bitstream.Bitstream {
@bitstream.Bitstream::new_range(
view.data(),
view.start_offset(),
view.length(),
)
}
///|
/// `FrameContext`: the image header and an optional allocation tracker.
/// (The thread pool of upstream is dropped; everything runs sequentially.)
pub fn Frame::parse(
bs : @bitstream.Bitstream,
image_header : @image.ImageHeader,
tracker~ : @grid.AllocTracker? = None,
) -> Frame raise @bitstream.JxlError {
bs.zero_pad_to_byte()
let base_offset = bs.num_read_bits() / 8
let header = FrameHeader::parse(bs, image_header)
let width = header.width.reinterpret_as_uint().to_uint64()
let height = header.height.reinterpret_as_uint().to_uint64()
if width > 1UL << 30 {
raise ProfileConformance("frame width too large")
}
if height > 1UL << 30 {
raise ProfileConformance("frame height too large")
}
if width * height > 1UL << 40 {
raise ProfileConformance("frame area too large")
}
let has_extra = !header.ec_blending_info.is_empty()
let all_blending = [header.blending_info, ..header.ec_blending_info]
for blending_info in all_blending {
if blending_info.mode.use_alpha() && has_extra {
let alpha_idx = blending_info.alpha_channel
guard alpha_idx >= 0 && alpha_idx < image_header.metadata.ec_info.length() else {
raise ValidationFailed("blending_info.alpha_channel out of range")
}
let alpha_ec_info = image_header.metadata.ec_info[alpha_idx]
if !alpha_ec_info.is_alpha() {
raise ValidationFailed(
"blending_info.alpha_channel is not the type of Alpha",
)
}
}
}
if header.flags.use_lf_frame() && header.lf_level >= 4 {
raise ValidationFailed("lf_level out of range")
}
let color_upsampling_shift = header.upsampling.ctz()
let n = @cmp.minimum(
header.ec_upsampling.length(),
image_header.metadata.ec_info.length(),
)
for i in 0.. 6 {
raise ValidationFailed("cumulative EC upsampling factor is too large")
}
let actual_dim_shift = ec_upsampling_shift +
dim_shift -
color_upsampling_shift
if actual_dim_shift > 7 + header.group_size_shift {
raise ValidationFailed("dim_shift too large")
}
}
if header.width == 0 || header.height == 0 {
raise ValidationFailed(
"Invalid crop dimensions for frame: zero width or height",
)
}
let toc = Toc::parse(bs, header)
toc.adjust_offsets(base_offset)
let data = toc.iter_bitstream_order().map(GroupData::from_toc_group)
let passes = header.passes
let pass_shifts = @sorted_map.SortedMap([])
let mut maxshift = 3
for
i in 0..<@cmp.minimum(passes.downsample.length(), passes.last_pass.length()) {
let downsample = passes.downsample[i]
let last_pass = passes.last_pass[i]
let minshift = downsample.ctz()
pass_shifts.set(last_pass, (minshift, maxshift))
maxshift = minshift
}
pass_shifts.set(header.passes.num_passes - 1, (0, maxshift))
{
tracker,
image_header,
header,
toc,
data,
all_group_offsets: {
lf_group: 0,
hf_global: 0,
pass_group: 0,
has_error: 0,
},
reading_data_index: 0,
pass_shifts,
}
}
///|
pub fn Frame::alloc_tracker(self : Frame) -> @grid.AllocTracker? {
self.tracker
}
///|
pub fn Frame::image_header(self : Frame) -> @image.ImageHeader {
self.image_header
}
///|
/// Returns the frame header.
pub fn Frame::header(self : Frame) -> FrameHeader {
self.header
}
///|
/// Returns the TOC.
pub fn Frame::toc(self : Frame) -> Toc {
self.toc
}
///|
pub fn Frame::pass_shifts(
self : Frame,
) -> @sorted_map.SortedMap[Int32, (Int32, Int32)] {
self.pass_shifts
}
///|
pub fn Frame::data(self : Frame, group : TocGroupKind) -> BytesView? {
let idx = self.toc.group_index_bitstream_order(group)
if idx >= 0 && idx < self.data.length() {
Some(self.data[idx].view)
} else {
None
}
}
///|
/// Feeds frame data; returns the bytes not consumed by this frame.
pub fn Frame::feed_bytes(
self : Frame,
buf : BytesView,
) -> BytesView raise @bitstream.JxlError {
let mut buf = buf
while self.reading_data_index < self.data.length() {
let group_data = self.data[self.reading_data_index]
group_data.ensure_allocated(self.tracker)
let bytes_left = group_data.toc_group.size - group_data.len()
if buf.length() < bytes_left {
group_data.append(buf)
return buf[buf.length():]
}
group_data.append(buf[:bytes_left])
buf = buf[bytes_left:]
self.reading_data_index += 1
}
buf
}
///|
pub fn Frame::current_loading_group(self : Frame) -> TocGroup? {
let groups = self.toc.iter_bitstream_order()
if self.reading_data_index < groups.length() {
Some(groups[self.reading_data_index])
} else {
None
}
}
///|
pub fn Frame::is_loading_done(self : Frame) -> Bool {
self.reading_data_index >= self.data.length()
}
///|
/// Adjusts the cropping region of the image to the actual decoding region of the frame.
///
/// The cropping region of the *image* needs to be adjusted to be used in a *frame*, for a few
/// reasons:
/// - A frame may be blended to the canvas with offset, which makes the image and the frame
/// have different coordinates.
/// - Some filters reference other samples, which requires padding to the region.
///
/// This method takes care of those and returns the adjusted region `(left, top, width, height)`.
pub fn Frame::adjust_region(
self : Frame,
region : (Int32, Int32, Int32, Int32),
) -> (Int32, Int32, Int32, Int32) {
let (left, top, width, height) = region
let mut left = left.reinterpret_as_uint()
let mut top = top.reinterpret_as_uint()
let mut width = width.reinterpret_as_uint()
let mut height = height.reinterpret_as_uint()
if self.header.have_crop {
left = saturating_add_signed(left, -self.header.x0)
top = saturating_add_signed(top, -self.header.y0)
}
let mut padding = 0U
if self.header.restoration_filter.gab.enabled() {
padding = 1
}
if self.header.restoration_filter.epf.enabled() {
padding = 3
}
if padding > 0 {
let delta_w = if left < padding { left } else { padding }
let delta_h = if top < padding { top } else { padding }
left -= delta_w
top -= delta_h
width += delta_w + padding
height += delta_h + padding
}
(
left.reinterpret_as_int(),
top.reinterpret_as_int(),
width.reinterpret_as_int(),
height.reinterpret_as_int(),
)
}
///|
/// `u32::saturating_add_signed`.
fn saturating_add_signed(a : UInt32, b : Int32) -> UInt32 {
let r = a.to_uint64().reinterpret_as_int64() + b.to_int64()
if r < 0L {
0
} else if r > 0xffffffffL {
0xffffffffU
} else {
r.to_uint()
}
}